Skip to main content

@cortexa/contracts

Project Overview​

@cortexa/contracts is the shared contract package for the Cortexa ecosystem. It defines Zod runtime validation schemas and matching inferred TypeScript types for payloads exchanged between independently developed Cortexa modules.

The repository exists to reduce contract drift across services, integrations, workers, APIs, automation agents, and other consumers that need a common vocabulary for documents, connectors, events, processing results, extraction outputs, AI-adjacent results, and shared platform primitives.

This package is a contract boundary. It is not an application, service, connector implementation, workflow engine, AI pipeline, API server, UI, or persistence layer.

Key Responsibilities​

  • Own canonical shared payload schemas for Cortexa systems.
  • Export TypeScript types inferred from those schemas.
  • Provide shared enums and vocabularies used across package and service boundaries.
  • Define common result envelopes, lifecycle status shapes, identifiers, timestamps, metadata, errors, pagination, money, audit, schema version, and external reference contracts.
  • Keep runtime behavior, storage, transport, orchestration, provider integrations, and business workflows outside this repository.

Current Status​

Implemented capabilities:

  • Single-package TypeScript library published as @cortexa/contracts.
  • Zod-based schema definitions under src/.
  • Public package exports through src/index.ts and per-domain barrel files.
  • Contract areas for common primitives, documents, connectors, events, AI-adjacent results, and extraction outputs.
  • TypeScript declaration output configured through the package build.
  • Repository documentation under docs/.

Planned capabilities:

  • No future capabilities are explicitly documented in the current repository corpus. New planned work should be documented under docs/ when it changes repository responsibilities, organization, or architectural direction.

Getting Started​

This repository is a small TypeScript package. Start by reviewing the documentation, then inspect the public package surface in src/index.ts.

Typical local orientation:

npm install
npm run build

Key technologies:

  • TypeScript
  • Zod
  • NPM package metadata and lockfile

Begin with:

  • src/index.ts for the public package entrypoint.
  • src/common for shared primitives.
  • Domain folders under src/ for contract areas.
  • docs/ARCHITECTURE.md before changing responsibilities or boundaries.
  • docs/REPOSITORY.md before adding or moving source files.

Documentation​

The documentation corpus is intentionally small and source-of-truth oriented:

  • docs/ARCHITECTURE.md: architectural source of truth for purpose, ecosystem role, responsibilities, boundaries, constraints, and design principles.
  • docs/REPOSITORY.md: repository organization source of truth for folder responsibilities, public exports, module ownership, dependency rules, and code placement guidance.

Additional long-lived documentation should live under docs/ and be linked from the appropriate entrypoint.

Architecture Summary​

The package follows a contract-first architecture. Zod schemas are the source of truth for shared payload shapes, and TypeScript types are inferred from those schemas so runtime validation and compile-time typing stay aligned.

The repository owns data contracts only. Consumers own validation call sites, transport serialization, persistence, security, orchestration, connector behavior, AI execution, and application workflows.

Read docs/ARCHITECTURE.md for the full architectural model and boundary rules.

Repository Organization Summary​

The repository is organized as a single TypeScript library. Source code lives under src/, grouped by contract area:

  • common
  • documents
  • connectors
  • events
  • ai
  • extraction

Each area exposes public contracts through its index.ts barrel, and the package root re-exports those areas from src/index.ts.

Read docs/REPOSITORY.md for repository navigation, ownership rules, and code placement guidance.

Contributing​

Before making structural or contract changes:

  • Read the architecture and repository guides.
  • Follow existing schema, type, naming, file, and export conventions.
  • Treat exported schemas and inferred types as public contracts.
  • Prefer additive contract evolution when possible.
  • Keep runtime implementation logic out of this package.
  • Update documentation when implementation changes affect responsibilities, boundaries, organization, or contributor guidance.

Documentation Philosophy​

README.md is the repository landing page and documentation entrypoint. It should stay concise, accessible, and useful for both humans and AI systems.

docs/ARCHITECTURE.md is the architectural source of truth.

docs/REPOSITORY.md is the repository organization source of truth.

Detailed documentation belongs under docs/. The README should summarize and route readers to the right document rather than duplicate architecture, repository navigation, API details, database details, or implementation inventories.