Skip to main content

Architecture

Repository Purpose​

@cortexa/contracts exists to define shared data contracts for the Cortexa ecosystem. It centralizes runtime validation schemas and their inferred TypeScript types so independently developed Cortexa modules can exchange document, connector, processing, extraction, AI, and common platform payloads without redefining those shapes locally.

The repository solves contract drift. Its primary output is a TypeScript package whose public API exposes Zod schemas and matching TypeScript types. Consumers use those schemas at process, API, queue, adapter, and persistence boundaries where a shared payload shape is required.

This repository is not an application, service, workflow engine, connector implementation, AI pipeline, or persistence layer.

Ecosystem Role​

This repository acts as a shared contract kernel for Cortexa. It sits between systems that produce domain payloads and systems that consume or persist those payloads.

External consumers include Cortexa services, applications, integration packages, background workers, API layers, and automation agents that import @cortexa/contracts.

Upstream dependencies are intentionally narrow:

  • zod for runtime schema definition and validation.
  • TypeScript for declaration generation and package compilation.
  • Domain vocabularies represented by provider, source, document type, entity type, and status enums.

Downstream dependencies are the packages and services that depend on the published contracts. This repository does not name or configure downstream deployments directly.

Related repositories are not declared in this repository. Architecturally, related repositories are expected to include Cortexa services that implement ingestion, connector synchronization, document processing, extraction, search, API transport, storage, or user-facing workflows.

External systems represented in the contracts include provider and document sources such as Google Drive, Gmail, Slack, WhatsApp, filesystems, manual input, and unknown sources. The repository models identifiers, metadata, payloads, and capabilities for those integrations, but it does not connect to the systems.

Architectural Responsibilities​

This repository owns:

  • Canonical Zod schemas for shared Cortexa payloads.
  • Inferred TypeScript types derived from those schemas.
  • Shared enums and value vocabularies for cross-system interoperability.
  • Common result envelopes and lifecycle status shapes used by processing-oriented modules.
  • Lightweight common primitives such as identifiers, timestamps, money, pagination, errors, audit metadata, schema version metadata, and external references.
  • Public package exports that make contracts available to consumers from a single package boundary.

This repository delegates:

  • Connector behavior, authentication, provider API calls, download/upload logic, and sync orchestration to integration repositories or services.
  • Document ingestion, OCR, parsing, classification execution, normalization algorithms, and extraction algorithms to processing services.
  • AI model invocation, embedding generation, ranking, retrieval, and search infrastructure to AI or search services.
  • API routing, transport serialization, authorization, tenancy enforcement, and request handling to application or service layers.
  • Persistence, migrations, repositories, indexes, queues, object storage, and database ownership to infrastructure and service repositories.
  • Business workflows, retries, scheduling, state transitions, and operational observability to runtime systems.

System Boundaries​

Inside the repository boundary are shared contract definitions, package metadata, TypeScript build configuration, and source modules that define schemas and inferred types.

Outside the repository boundary are all runtime implementations. The contracts may describe a connector file, an ingestion event, an extracted invoice, or an embedding result, but this package does not produce those values by itself.

Important ownership boundaries:

  • Schemas are owned here; validation call sites are owned by consumers.
  • Enum values are owned here; provider-specific mapping logic is owned by integration layers.
  • Result envelopes are owned here; execution semantics and lifecycle transitions are owned by processing and orchestration systems.
  • Metadata extension fields are structurally allowed here; field-level meaning and governance are owned by producers and consumers.
  • Timestamps are currently modeled as JavaScript Date values; cross-process serialization policy is owned outside this package.

Integration points are the package import boundary, generated TypeScript declarations, and runtime Zod validators.

High-Level Architecture​

The architecture is a contract-first TypeScript package organized around domain contract areas rather than runtime layers.

The public package entrypoint re-exports contract areas for:

  • Common primitives shared across domains.
  • Document payloads and document lifecycle representations.
  • Connector metadata, capabilities, file descriptions, download payloads, and sync result shapes.
  • Event and processing context contracts.
  • AI-adjacent result shapes for processing, embeddings, and search.
  • Extraction result envelopes and extracted business document payloads.

The dominant organization pattern is schema-plus-type pairing: each exported contract is represented by a Zod schema and a TypeScript type inferred from that schema. This makes runtime validation and compile-time typing derive from the same source.

The implementation is mostly data-model composition. Some contracts extend base records or processing result envelopes; others compose shared enums and primitives. The package does not define domain services, classes, repositories, transport clients, or executable workflows.

The current dependency structure is not a strict layered DAG. Common primitives are generally foundational, but there is observable cross-domain composition, such as external references using document sources, processing results using event statuses, event batch results extending processing results, and connector results composing document and event contracts. New contracts should treat that coupling as a compatibility concern.

Domain Overview​

The repository represents a document-processing domain with integration and AI-processing boundaries.

Primary domain concepts are:

  • Source artifacts: files or documents obtained from external providers, manual input, or filesystems.
  • Raw documents: source-bound payloads with optional text, binary data, tables, external references, and metadata.
  • Normalized documents: processed document representations with type, extracted text, confidence, entities, parsed content, and metadata.
  • Connectors: provider identity, advertised capabilities, external file descriptors, downloaded payloads, and synchronization summaries.
  • Events and processing context: ingestion events, workflow step identifiers, status values, correlation context, and batch outcome summaries.
  • AI and extraction outputs: processing result envelopes, embeddings, search hits, generic extraction output, and currently modeled invoice and receipt extractions.
  • Common primitives: shared low-level structures reused by multiple domains.

This overview is intentionally limited to architectural concepts. Detailed field-level semantics belong with contract definitions and domain documentation.

Contracts and Integration Points​

The primary contract surface is the @cortexa/contracts package. Consumers import schemas and types from the package and use schemas to validate payloads crossing system boundaries.

Significant contract categories include:

  • Runtime validation contracts: Zod schemas named with the Schema suffix.
  • Static typing contracts: TypeScript types inferred from the schemas.
  • Event contracts: ingestion events, event status, processing context, workflow steps, and batch outcomes.
  • Connector contracts: provider definitions, capabilities, remote file descriptions, downloaded files, and sync summaries.
  • Document contracts: raw and normalized document shapes, classifications, document entities, parsed content, source enums, and document type enums.
  • AI and extraction contracts: result envelopes, embeddings, search results, extraction envelopes, and extracted invoice or receipt payloads.
  • Common contracts: base records, timestamps, money, pagination, API errors, audit metadata, schema versions, and external references.

The package intentionally provides contracts, not adapters. For example, a Google Drive integration can map provider data into a connector file contract, and a document processor can map its output into a normalized document contract, but the mapping code lives outside this repository.

Infrastructure Responsibilities​

This repository has minimal infrastructure responsibility.

Storage and persistence are not owned here. The package does not define tables, migrations, repositories, object storage conventions, indexes, or database access abstractions.

Security is not implemented here. The package does not define authentication, authorization, tenant isolation, encryption, secret management, or data retention behavior. Consumers must apply security controls before and after using these contracts, especially for raw document payloads, binary content, metadata, external identifiers, and AI outputs.

Configuration is limited to package and TypeScript build configuration. Runtime configuration belongs to consuming services.

Orchestration is represented only as data. Event status, workflow step, processing context, and result contracts can describe execution state, but this package does not schedule work, enforce transitions, retry operations, or emit telemetry.

Architectural Constraints and Invariants​

The following rules should remain true unless the repository changes architectural purpose:

  • The package remains implementation-agnostic. It defines payload contracts, not runtime behavior.
  • Zod schemas are the source of truth for exported contract shapes; TypeScript types should be inferred from those schemas.
  • Public contracts should be exported through the package boundary rather than consumed through private internal paths.
  • Contract changes must account for downstream compatibility. Removing fields, changing enum values, tightening validation, or changing timestamp representation can be breaking.
  • Cross-domain imports should be deliberate and minimal because they couple contract areas that may be consumed independently.
  • Open metadata records are extension points, not a substitute for canonical fields that multiple systems must understand consistently.
  • Provider/source enums define shared vocabulary only; they do not imply that a connector implementation exists in this repository.
  • Processing status contracts describe state labels only; they do not define state transition rules.
  • Date-valued contracts currently use JavaScript Date semantics; transport serialization must be handled consistently by consumers.
  • The package should not acquire dependencies on service frameworks, API frameworks, databases, queues, cloud SDKs, or AI provider SDKs.

Extensibility and Design Principles​

The implementation reflects a small shared-kernel design:

  • Contracts are centralized so producer and consumer modules can share validation semantics.
  • Runtime schemas and compile-time types are paired to reduce schema/type divergence.
  • Domain modules stay lightweight and data-oriented.
  • Common envelopes, base records, statuses, and primitives reduce duplicated cross-system conventions.
  • Optional metadata fields provide controlled flexibility for provider-specific or pipeline-specific data.
  • Specific domain payloads, such as extracted invoice and receipt data, are separated from generic result envelopes.
  • External provider support is represented as vocabulary and payload shape, while behavior remains outside the package.

Extensibility should favor additive contract evolution. New optional fields, new specialized schemas, or new enum values may still affect consumers and should be reviewed as contract changes.

Documentation Corpus Map​

The standard documentation corpus is:

  • README.md: repository landing page and short package summary.
  • /docs/ARCHITECTURE.md: architectural entrypoint and source of truth for responsibilities, boundaries, ecosystem role, and design intent.
  • /docs/REPOSITORY.md: repository organization guide for folder structure, package organization, and code placement guidance.

Use this document for architectural orientation. Use /docs/REPOSITORY.md for repository navigation and code organization decisions. Additional documents under /docs should be referenced from the appropriate entrypoint without duplicating architectural responsibilities.

Guidance for Developers and AI Agents​

Start with this document to understand what the repository owns and what it intentionally delegates. Then use README.md for the package-level summary and /docs/REPOSITORY.md for organization and placement guidance.

When changing this repository:

  • Treat exported schemas and inferred types as public contracts.
  • Prefer extending existing schema patterns over introducing alternate validation mechanisms.
  • Check whether a change affects consumers at runtime, compile time, or both.
  • Keep implementation logic out of contracts; place runtime behavior in the appropriate consuming service or integration repository.
  • Avoid broadening dependencies unless they are required for schema definition or package compilation.
  • Keep metadata fields for genuinely variable or provider-specific data; promote repeated cross-system fields into explicit schemas.
  • Update this architecture document only when responsibilities, boundaries, contract strategy, dependency direction, or ecosystem role changes.

When using this repository from another system:

  • Import from the package boundary.
  • Validate inbound and outbound payloads with the corresponding schema.
  • Map external provider, storage, transport, and AI-service data into these contracts at system boundaries.
  • Do not assume that a represented provider, event, or result shape means the runtime implementation exists here.