Skip to main content

Repository Guide

Repository Purpose​

This repository contains the TypeScript SDK package for Cortexa document ingestion and normalization. The current implementation scope is a small SDK package that exposes typed document processing helpers, SDK-local request and response types, and an HTTP client for calling a configured Cortexa service.

This document is the repository navigation and code organization guide. Architectural responsibilities, system boundaries, design principles, ecosystem role, and architectural constraints are documented in /docs/ARCHITECTURE.md.

Repository Organization Overview​

The repository is organized as a single-package TypeScript SDK. It is not currently a monorepo and does not contain multiple workspace packages.

The implementation uses a lightweight layer-based organization under src:

  • types contains package-facing type exports and SDK-local interfaces.
  • client contains HTTP client access to external Cortexa service endpoints.
  • processors contains orchestration functions for local document processing.
  • parsers contains parsing helpers that adapt raw document input into parsed content.
  • normalizers contains normalization helpers that adapt parsed content into normalized output.
  • schemas is present as a source area for runtime schema definitions, but the current schema files are empty.

Examples live outside src under examples. Documentation lives under docs. Build and package configuration live at the repository root.

High-Level Repository Tree​

.
|-- docs/
|   |-- ARCHITECTURE.md
|   `-- REPOSITORY.md
|-- examples/
|   `-- process-document.ts
|-- src/
|   |-- client/
|   |-- normalizers/
|   |-- parsers/
|   |-- processors/
|   |-- schemas/
|   |-- types/
|   `-- index.ts
|-- package.json
|-- package-lock.json
|-- tsconfig.json
`-- tsup.config.ts

Generated build output is configured to be emitted under dist, but dist is not a source-of-truth repository area.

Top-Level Directory Responsibilities​

src/​

Responsibility: SDK source code compiled into the published package.

What belongs here:

  • Public exports reachable through src/index.ts.
  • SDK client code.
  • Local processing, parsing, and normalization functions.
  • SDK-local types and re-exports of shared contract types.
  • Runtime schemas when they are implemented.

What should not belong here:

  • Usage examples.
  • Generated build output.
  • Repository documentation.
  • Backend service implementations, persistence layers, deployment configuration, or application-specific workflows.

Relationship with other areas: src is compiled by tsup using the root TypeScript and build configuration. Examples import from src for local demonstration. Documentation should describe src organization but should not duplicate implementation details.

examples/​

Responsibility: Minimal runnable examples that demonstrate SDK usage.

What belongs here:

  • Small scripts showing how consumers call exported SDK APIs.
  • Example input construction for local development or documentation support.

What should not belong here:

  • Reusable SDK logic.
  • Test-only fixtures that are not examples.
  • Production application code.

Relationship with other areas: examples should import the package surface or local source entrypoint instead of reaching deeply into implementation modules unless the example is specifically about an internal development workflow.

docs/​

Responsibility: Long-lived repository documentation.

What belongs here:

  • /docs/ARCHITECTURE.md for system responsibilities, architectural boundaries, design principles, ecosystem role, and architectural constraints.
  • /docs/REPOSITORY.md for repository navigation, organization, ownership, and code placement guidance.
  • Additional focused documentation when it supports contributors without duplicating architecture or implementation source.

What should not belong here:

  • Generated API output unless explicitly adopted as documentation.
  • Build artifacts.
  • Feature inventories that mirror source files without adding navigation value.

Relationship with other areas: documentation should reflect the repository as implemented. Structural changes to folders, modules, package exports, or code placement conventions should update this guide.

Root Configuration Files​

Responsibility: Package metadata, dependency locking, TypeScript compiler settings, and build configuration.

What belongs here:

  • package.json for package metadata, scripts, entrypoints, and dependencies.
  • package-lock.json for npm dependency locking.
  • tsconfig.json for TypeScript compiler configuration.
  • tsup.config.ts for package build configuration.

What should not belong here:

  • SDK source modules that belong under src.
  • Documentation that belongs under docs.
  • Example scripts that belong under examples.

Relationship with other areas: root configuration controls how src/index.ts is compiled into the package outputs declared by package.json.

Modules and Package Organization​

Package Entrypoint: src/index.ts​

Purpose: Defines the public source entrypoint for the SDK package.

Responsibility: Re-export supported SDK modules from types, normalizers, parsers, client, and processors.

Reusability level: Public package surface. Consumers should prefer imports from the package entrypoint over internal file paths.

Dependency relationships: The entrypoint depends on module barrel files. It should not contain implementation logic.

Types: src/types/​

Purpose: Provide SDK-facing TypeScript types.

Responsibility: Export SDK-local interfaces such as CortexaInput and CortexaOutput, and re-export shared document types from @cortexa/contracts.

Reusability level: Public package surface when exported through src/index.ts.

Dependency relationships: Type re-export files depend on @cortexa/contracts. SDK-local request and response interfaces are owned by this package.

Client: src/client/​

Purpose: Provide the SDK HTTP client.

Responsibility: Own the CortexaClient class and its HTTP calls through axios.

Reusability level: Public SDK runtime API.

Dependency relationships: Depends on SDK-local input/output types and HTTP transport dependencies. Processing, parsing, and normalization modules should not depend on the client unless an explicit repository-level responsibility change is made.

Processors: src/processors/​

Purpose: Coordinate local document processing flows.

Responsibility: Own processDocument, which currently composes parsing and normalization.

Reusability level: Public SDK runtime helper when exported through the package entrypoint.

Dependency relationships: Depends on parser and normalizer modules, and on shared document contract types. Processors should coordinate existing steps rather than own low-level parsing or normalization details directly.

Parsers: src/parsers/​

Purpose: Adapt raw document input into parsed content.

Responsibility: Own document parsing helpers such as parseDocument.

Reusability level: Public SDK helper if exported through the package entrypoint. The current parsers/index.ts does not export parseDocument, so parser availability through the root entrypoint should be verified before relying on it as public API.

Dependency relationships: Depends on shared contract types from @cortexa/contracts. Parser modules should not call the HTTP client or own normalized output construction.

Normalizers: src/normalizers/​

Purpose: Adapt parsed content into normalized document output.

Responsibility: Own normalization helpers such as normalizeDocument.

Reusability level: Public SDK helper when exported through the package entrypoint.

Dependency relationships: Depends on shared contract types and Node runtime APIs used by normalization. Normalizers should not call service endpoints or own parsing concerns.

Schemas: src/schemas/​

Purpose: Reserved source area for runtime schema definitions.

Responsibility: Currently no implemented schemas are present. If runtime validation is added, schema files should live here and be exported through src/schemas/index.ts only when intended for package consumers.

Reusability level: Not currently public in practice because the schema files are empty and src/index.ts does not export schemas.

Dependency relationships: Schemas should align with shared contracts and SDK-local types. They should not create competing domain definitions.

Dependency and Boundary Rules​

  • Package consumers should import through the SDK package entrypoint rather than internal module paths.
  • src/index.ts should remain a re-export layer and should not accumulate implementation logic.
  • types may re-export shared contract types from @cortexa/contracts; it should not duplicate contract-owned document shapes.
  • processors may compose parsers and normalizers.
  • parsers should transform raw document input into parsed content and should not depend on client or processor modules.
  • normalizers should transform parsed content into normalized output and should not depend on client or processor modules.
  • client should isolate HTTP transport behavior and should not be required by local parsing or normalization helpers.
  • examples may depend on exported SDK APIs, but SDK source code should not depend on examples.
  • docs must not be imported by runtime code.
  • Build output under dist is generated from src and should not be edited as source.

Shared vs Implementation-Specific Components​

Shared infrastructure:

  • Root TypeScript and build configuration: tsconfig.json and tsup.config.ts.
  • Package metadata and dependency lockfiles: package.json and package-lock.json.

Shared libraries:

  • Reusable SDK modules under src when exported through src/index.ts.
  • client, processors, normalizers, and exported types are the current reusable SDK areas.

Shared contracts:

  • Shared document contract types are imported from @cortexa/contracts.
  • SDK-local request and response interfaces live under src/types.

Runtime applications:

  • No runtime application exists in this repository.
  • examples/process-document.ts is an example script, not an application layer.

Business or domain logic:

  • Local document processing helpers live under src/processors, src/parsers, and src/normalizers.
  • Canonical domain contract ownership remains outside this repository in @cortexa/contracts.

Presentation layers:

  • No UI or presentation layer exists in the current repository.

Integrations:

  • HTTP integration with a Cortexa service lives under src/client.
  • No provider-specific integration modules are implemented in the current source tree.

Experimental areas:

  • No explicit experimental directory exists. Experimental code should not be added ad hoc to existing source folders unless it is intended to become part of the SDK package surface.

Code Placement Guidance​

New domain functionality:

  • Add SDK-owned local transformation behavior under src/parsers, src/normalizers, or src/processors depending on whether the change parses input, normalizes parsed content, or coordinates a processing flow.
  • Add shared contract shape changes to @cortexa/contracts, not to this repository, when the type is canonical across Cortexa packages.

New API endpoint:

  • Add client methods under src/client when the endpoint is consumed by the SDK.
  • Add SDK-local input/output interfaces under src/types if the request or response shape is owned by this SDK.
  • Export the method through the existing client class rather than spreading HTTP calls across processing modules.

New UI component:

  • There is no UI layer in this repository. UI components belong in a consuming application or a dedicated UI package, not in this SDK.

New integration:

  • Add SDK HTTP service integration behavior under src/client.
  • Add provider-specific ingestion adapters only as explicit new source modules with clear exports and ownership. Do not hide provider logic inside generic parser, normalizer, or processor code.

New background job:

  • Background jobs do not belong in the current SDK structure. Put job orchestration in a consuming application or service repository.

New infrastructure component:

  • Build or package infrastructure belongs in root configuration files when it affects this package.
  • Runtime infrastructure, deployment, queues, persistence, and service orchestration belong outside this SDK repository.

New shared utility:

  • Add a utility only when it is reused by multiple SDK modules and fits the package boundary.
  • Keep utilities internal unless they are intentionally exported through src/index.ts.

New reusable package:

  • This repository is currently a single-package SDK. A new reusable package should not be added here without first changing the repository organization and updating this guide.

New runtime schema:

  • Add schema definitions under src/schemas.
  • Keep schema naming aligned with the related type or contract.
  • Export schemas from src/schemas/index.ts only when they are intended to be reused.
  • Add schemas to src/index.ts only when schemas are intentionally part of the public package surface.

New example:

  • Add usage demonstrations under examples.
  • Keep examples small and focused on exported SDK behavior.

New documentation:

  • Add repository navigation and code placement information to /docs/REPOSITORY.md.
  • Add architectural responsibility and boundary information to /docs/ARCHITECTURE.md.
  • Add focused docs under /docs when they do not duplicate these documents.

Repository Conventions​

  • TypeScript source lives under src.
  • The root package entrypoint is src/index.ts.
  • Source subdirectories use barrel index.ts files for module exports.
  • Module filenames use kebab case, such as process-document.ts and cortexa-client.ts.
  • Type-only contract re-exports live under src/types.
  • SDK-local interfaces use PascalCase names, such as CortexaInput and CortexaOutput.
  • Build output is produced by tsup from src/index.ts into dist.
  • The TypeScript compiler root is src, and current compiler inclusion is limited to src.
  • Examples live under examples and are outside the configured compiler input.
  • Documentation lives under docs.
  • @cortexa/contracts is consumed as a local file dependency from ../cortexa.contracts.

Documentation Corpus Map​

  • /docs/ARCHITECTURE.md: architectural entrypoint for system responsibilities, architectural boundaries, design principles, ecosystem role, architectural constraints, and ownership boundaries.
  • /docs/REPOSITORY.md: repository navigation, folder responsibilities, package organization, dependency direction, and code placement guidance.
  • /README.md: expected repository landing page role, but no README file is present in the current repository tree.

Do not duplicate /docs/ARCHITECTURE.md in this document. When a contributor needs to understand why the SDK has its current boundaries or what responsibilities are outside the repository, direct them to /docs/ARCHITECTURE.md.

Guidance for Developers and AI Agents​

Start with package.json to understand the package entrypoints, scripts, and dependencies. Then read src/index.ts to identify the public source export surface. Use this document to decide where code belongs before editing source files.

When changing exported behavior, check whether the relevant module is exported through its local barrel file and through src/index.ts. Keep new public APIs reachable through the package entrypoint. Keep internal helpers unexported unless consumers need them.

Before adding new types, check whether the type is SDK-local or belongs in @cortexa/contracts. Shared document shapes should not be redefined in this repository.

Keep changes close to the existing source area:

  • Client transport changes belong in src/client.
  • Processing orchestration belongs in src/processors.
  • Raw input parsing belongs in src/parsers.
  • Parsed content normalization belongs in src/normalizers.
  • SDK-local type definitions belong in src/types.
  • Runtime validation schemas belong in src/schemas.
  • Usage examples belong in examples.

Update this document when repository structure, module ownership, package exports, or code placement conventions change. Routine implementation changes inside an existing module usually do not require repository guide updates.