Skip to main content

Repository Guide

Repository Purpose​

@cortexa/contracts is a TypeScript package that defines shared runtime validation schemas and inferred TypeScript types for the Cortexa ecosystem.

The current implementation scope is limited to contract definitions under src/, package build metadata, and repository documentation under docs/. The repository does not contain runtime applications, API servers, UI code, connector implementations, background workers, persistence infrastructure, or deployment configuration.

Use this document as the repository navigation and code placement guide. Use /docs/ARCHITECTURE.md for system responsibilities, architectural boundaries, design principles, ecosystem role, and architectural constraints.

Repository Organization Overview​

This repository is a single-package TypeScript library. It is organized as a small contract package rather than a monorepo or application workspace.

The source layout is domain-area based:

  • src/common contains shared contract primitives and reusable record shapes.
  • src/documents contains document-related contract shapes and vocabularies.
  • src/connectors contains connector metadata, file, capability, download, and sync result contracts.
  • src/events contains event, processing context, status, workflow step, and batch result contracts.
  • src/ai contains AI-adjacent result contracts such as processing, embedding, and search results.
  • src/extraction contains extraction result envelopes and extracted business document contracts.

Each contract area has an index.ts barrel. The package root src/index.ts re-exports the contract areas as the public package surface.

High-Level Repository Tree​

.
|-- README.md
|-- package.json
|-- package-lock.json
|-- tsconfig.json
|-- docs/
|   |-- ARCHITECTURE.md
|   `-- REPOSITORY.md
`-- src/
    |-- index.ts
    |-- ai/
    |-- common/
    |-- connectors/
    |-- documents/
    |-- events/
    `-- extraction/

This tree is intentionally high level. It shows the navigation surface, not every contract file.

Top-Level Directory Responsibilities​

docs/​

Responsibility: repository documentation.

What belongs here:

  • Repository organization guides.
  • Architectural entrypoints.
  • Long-lived documentation that explains how contributors should understand or extend the package.

What should not belong here:

  • Generated API references unless the repository adopts a documentation generation workflow.
  • Deployment runbooks for runtime systems outside this package.
  • Field-by-field schema inventories that duplicate source files.

Relationship with other areas:

  • Documents under docs/ describe the repository and its source organization.
  • /docs/ARCHITECTURE.md owns architecture-level responsibilities and boundaries.
  • /docs/REPOSITORY.md owns navigation, ownership, and code placement guidance.

src/​

Responsibility: TypeScript source for the published @cortexa/contracts package.

What belongs here:

  • Zod schemas that define shared contract shapes.
  • TypeScript types inferred from those schemas.
  • Shared enums and vocabularies represented as schemas.
  • Barrel exports that define the package import surface.

What should not belong here:

  • Runtime services, controllers, workers, schedulers, repositories, or connector clients.
  • API routes, UI components, framework-specific adapters, migrations, or deployment code.
  • Business workflow implementations or side-effecting integration logic.

Relationship with other areas:

  • src/index.ts is the package entrypoint listed by the package build configuration.
  • package.json points compiled consumers to dist/index.js and dist/index.d.ts.
  • tsconfig.json compiles src/ to dist/.
  • Documentation should describe src/ organization without duplicating individual schema definitions.

Top-Level File Responsibilities​

README.md​

Repository landing page. It currently provides the short package summary.

package.json​

Package manifest for @cortexa/contracts. It defines:

  • Package name and version.
  • Runtime dependency on zod.
  • Development dependency on typescript.
  • Build script: npm run build, which runs tsc.
  • Published entrypoints: dist/index.js and dist/index.d.ts.

package-lock.json​

NPM lockfile for reproducible dependency installation.

tsconfig.json​

TypeScript build configuration. It compiles src/ with strict settings, NodeNext module resolution, declaration output, and dist/ as the output directory.

Modules and Package Organization​

Public Package Entrypoint​

src/index.ts re-exports the top-level contract areas:

export * from './documents'
export * from './connectors'
export * from './extraction'
export * from './events'
export * from './ai'
export * from './common'

New public contract areas must be exported from this file. New public contracts inside an existing area must be exported from that area's index.ts.

Files that are not reachable through the relevant barrel are not part of the current public area export surface. For example, src/documents/document-processing-result.ts exists in the repository but is not exported by src/documents/index.ts.

src/common​

Purpose: shared contract primitives.

Responsibility:

  • Base record shape.
  • Timestamp, money, pagination, cursor pagination, API error, audit, schema version, and external reference contracts.

Reusability level: highest within this package. These contracts are intended for reuse by other contract areas.

Dependency relationships:

  • Uses zod.
  • Mostly foundational.
  • external-reference.ts imports DocumentSourceSchema, so common is not a completely dependency-free leaf.

src/documents​

Purpose: document contract area.

Responsibility:

  • Raw and normalized document contracts.
  • Document metadata, parsed content, classifications, entities, document sources, document types, and entity types.

Reusability level: high for any consumer exchanging document payloads.

Dependency relationships:

  • Uses zod.
  • Imports shared primitives from src/common.
  • Provides document vocabularies that are imported by common, events, and connectors.

src/connectors​

Purpose: connector-facing contract area.

Responsibility:

  • Connector providers, capabilities, definitions, external file descriptions, downloaded files, and sync result summaries.

Reusability level: high for integration packages and services that describe connector outputs or sync activity.

Dependency relationships:

  • Uses zod.
  • Imports document contracts for file and source-related payloads.
  • Imports event or batch processing contracts for sync result composition.
  • Should not contain provider SDK calls, authentication flows, or sync orchestration.

src/events​

Purpose: event and processing-context contract area.

Responsibility:

  • Ingestion events, event metadata, status values, processing context, workflow steps, and batch processing result contracts.

Reusability level: high for systems that exchange lifecycle, batch, or processing context payloads.

Dependency relationships:

  • Uses zod.
  • Imports shared primitives from src/common.
  • Imports document source vocabulary from src/documents.
  • Provides EventStatusSchema, which is reused by src/ai.

src/ai​

Purpose: AI-adjacent result contracts.

Responsibility:

  • Generic processing result envelopes.
  • Embedding result shapes.
  • Search result shapes.

Reusability level: medium to high for consumers that represent AI, retrieval, or processing outputs.

Dependency relationships:

  • Uses zod.
  • processing-result.ts imports event status vocabulary from src/events.
  • Should not contain model clients, prompts, ranking algorithms, vector index code, or search infrastructure.

src/extraction​

Purpose: extraction output contract area.

Responsibility:

  • Generic extraction result envelope.
  • Extracted invoice and extracted receipt contracts.

Reusability level: medium to high for consumers that exchange structured extraction outputs.

Dependency relationships:

  • Uses zod.
  • Imports shared primitives such as money and timestamp from src/common.
  • Imports the generic processing result envelope from src/ai.
  • Should not contain extraction algorithms, OCR logic, parser implementations, or model invocation code.

Dependency and Boundary Rules​

Repository-level dependency rules observable in the current implementation:

  • zod is the only runtime library dependency used by contracts.
  • Zod schemas are the source of truth for contract shapes.
  • TypeScript types are inferred from schemas with z.infer.
  • Public contracts should be reachable through barrel exports.
  • The package root should export contract areas, not unrelated implementation internals.
  • Contract files may compose schemas from other contract areas when a shared payload shape requires it.
  • Cross-area imports create public coupling and should stay deliberate.
  • Common primitives should be reused instead of redefining repeated low-level shapes.
  • This repository must not acquire dependencies on service frameworks, UI frameworks, databases, queues, provider SDKs, cloud SDKs, or AI provider SDKs for contract definitions.

This is a repository organization guide. Architectural implications and compatibility constraints are covered in /docs/ARCHITECTURE.md.

Shared vs Implementation-Specific Components​

Shared Infrastructure​

Current shared infrastructure is limited to package and build configuration:

  • package.json
  • package-lock.json
  • tsconfig.json

There is no runtime infrastructure code in this repository.

Shared Libraries​

The repository itself is the shared library. The reusable source is under src/, organized by contract area.

Shared Contracts​

Shared contracts are the primary owned artifact. They live under:

  • src/common
  • src/documents
  • src/connectors
  • src/events
  • src/ai
  • src/extraction

Runtime Applications​

No runtime applications currently exist in this repository. Application code should be placed in the consuming repository that owns execution.

Business or Domain Logic​

This repository contains data contracts and vocabularies only. Business logic, domain services, workflows, state transitions, and execution behavior should not be added here.

Presentation Layers​

No presentation layer currently exists. UI components, pages, design systems, and frontend state management belong outside this package.

Integrations​

This repository contains connector contracts, not connector implementations. Provider-specific adapters, clients, authentication, synchronization, file transfer, retries, and API mappings belong in integration or service repositories.

Experimental Areas​

No experimental directory exists. Do not add an experimental area unless the repository structure is intentionally changed and this document is updated in the same change.

Code Placement Guidance​

New Shared Primitive​

Add it under src/common when the shape is broadly reusable across more than one contract area or represents a low-level cross-system convention.

Export it from src/common/index.ts. If it is part of the public package surface, it will then be reachable through src/index.ts.

New Document Contract​

Add it under src/documents when it describes document payloads, document metadata, document classification, document content, document entities, document types, document sources, or normalized/raw document structures.

Export public additions from src/documents/index.ts.

New Connector Contract​

Add it under src/connectors when it describes connector definitions, provider capabilities, remote file descriptors, downloaded connector payloads, or sync result shapes.

Do not add provider API calls or synchronization behavior here.

New Event or Processing Context Contract​

Add it under src/events when it describes ingestion events, event statuses, workflow step identifiers, processing context, metadata, or batch processing summaries.

Do not add queue consumers, schedulers, retry behavior, telemetry emission, or workflow execution logic here.

New AI Result Contract​

Add it under src/ai when it describes processing outcomes, embeddings, search results, or AI-adjacent result payloads.

Do not add model provider clients, prompt execution, vector index code, or ranking logic here.

New Extraction Contract​

Add it under src/extraction when it describes structured extraction output or a result envelope for extracted data.

Do not add parser implementations, OCR, model calls, or extraction workflows here.

New API Endpoint​

Do not add API endpoints to this repository. Define only the shared request, response, event, or payload contracts here if they are meant to be reused by more than one consumer. The endpoint implementation belongs in the application or service repository that owns transport behavior.

New UI Component​

Do not add UI components to this repository. If UI code needs contract types, consume them from the published package.

New Integration​

Do not add integration runtime code here. Add only provider-neutral or provider-vocabulary contracts that are part of the shared package surface. The connector implementation belongs in an integration or service repository.

New Background Job​

Do not add background jobs here. If a job emits or consumes a shared payload, add or update the corresponding contract under the appropriate src/ area.

New Infrastructure Component​

Do not add infrastructure components here unless they are required for building this package. Runtime infrastructure, database definitions, queue configuration, object storage conventions, and deployment files belong outside this contracts package.

New Reusable Package​

This repository currently contains one package. Do not add another package or workspace without intentionally changing the repository organization and updating this guide.

Repository Conventions​

Observable conventions in the current implementation:

  • Contract source files use kebab-case filenames, such as raw-document.ts and connector-sync-result.ts.
  • Schema exports use the NameSchema suffix.
  • Type exports use the matching Name identifier inferred from the schema.
  • Runtime validators are defined with zod.
  • Types are derived with z.infer<typeof NameSchema>.
  • Contract composition uses schema reuse, including .extend(...) for derived object shapes.
  • Each contract area has an index.ts barrel file.
  • The package root src/index.ts re-exports contract areas.
  • Imports usually target specific sibling files or area barrels, depending on locality.
  • Generated build output is configured for dist/; source code belongs in src/.
  • TypeScript is configured with strict: true.
  • The module system is configured as NodeNext.

Do not introduce a different validation library, type-generation pattern, naming convention, or export style without an explicit repository-level decision.

Documentation Corpus Map​

The repository documentation corpus is:

  • README.md: repository landing page and short package summary.
  • /docs/ARCHITECTURE.md: architectural entrypoint. Use it for system responsibilities, architectural boundaries, design principles, ecosystem role, architectural constraints, and compatibility implications.
  • /docs/REPOSITORY.md: repository navigation and code organization guide. Use it for folder responsibilities, module ownership, dependency direction, and code placement decisions.

Additional documentation under /docs should be linked from the appropriate entrypoint and should not duplicate the responsibilities of these documents.

Guidance for Developers and AI Agents​

Start with README.md for the package summary, then read /docs/ARCHITECTURE.md for architectural boundaries and this document for repository navigation.

When modifying the repository:

  • Identify the contract area before editing.
  • Prefer adding a schema and inferred type in the area that owns the payload.
  • Reuse existing schemas from src/common or another contract area when that relationship already matches the payload.
  • Export public contracts through the relevant area barrel.
  • Confirm the root package entrypoint exposes any new public area.
  • Avoid adding runtime implementation code to contract modules.
  • Treat cross-area imports as coupling and keep them narrow.
  • Update this guide when folders, modules, package organization, or placement conventions change.
  • Update /docs/ARCHITECTURE.md only when responsibilities, boundaries, ecosystem role, design principles, or architectural constraints change.

For AI coding agents, do not infer missing applications, services, or infrastructure from represented contract names. A schema describing a connector, event, extraction result, or AI output does not mean the implementation exists in this repository.