Skip to main content

Architecture

Repository Purpose​

This repository provides the TypeScript SDK for Cortexa document ingestion and normalization. Its purpose is to give consumers a small, typed integration surface for turning raw document inputs into normalized document structures and for calling a Cortexa analysis service over HTTP.

The repository exists at the SDK boundary. It is responsible for client-side package exports, local document processing helpers, and transport-level access to Cortexa service endpoints. It is not the canonical domain model repository, not the backend analysis service, and not the persistence or orchestration layer for Cortexa.

Ecosystem Role​

@cortexa/sdk sits between external TypeScript/Node.js consumers and the broader Cortexa platform.

External consumers include applications, ingestion jobs, examples, tests, or developer tooling that need to submit document data to Cortexa or normalize document-like inputs before handing them to another layer.

Upstream dependencies include:

  • @cortexa/contracts, which owns shared domain contract types used by the SDK, including raw, parsed, and normalized document shapes.
  • Node.js runtime APIs, currently used for UUID generation.
  • HTTP transport dependencies used by the SDK client.

Downstream dependencies are any applications or packages that import @cortexa/sdk as their integration library. Those consumers depend on the SDK's exported functions, types, and client behavior remaining stable at the package boundary.

Related repositories include the @cortexa/contracts package referenced as a local file dependency at ../cortexa.contracts. That package is outside this repository boundary and should be treated as the source of truth for shared Cortexa contracts.

External systems include the Cortexa HTTP service exposed through the configured baseURL. The SDK currently assumes service endpoints for health checks and analysis, but it does not own those endpoints or their server-side behavior.

Architectural Responsibilities​

This repository owns:

  • The public TypeScript package interface exported from the SDK entrypoint.
  • Client-side access to Cortexa service endpoints.
  • A local document processing pipeline that parses a raw document into parsed content and normalizes parsed content into a normalized document.
  • SDK-specific request and response types for the HTTP analysis client.
  • Build configuration for producing JavaScript and declaration outputs from TypeScript source.

This repository delegates:

  • Canonical shared document contracts to @cortexa/contracts.
  • Backend analysis, classification, summarization, enrichment, and persistence to Cortexa services outside this repository.
  • Storage and database ownership to infrastructure or service repositories outside this SDK.
  • Runtime orchestration, job scheduling, retries, queues, and deployment concerns to consuming systems.
  • Authentication, authorization, tenancy enforcement, and network security policy to service and infrastructure layers. The current SDK implementation does not enforce those concerns.
  • Runtime schema validation. Schema files are present in the source tree, but no validation schemas are currently implemented.

System Boundaries​

Inside the repository boundary:

  • SDK source code under src.
  • Package-level type exports and local TypeScript interfaces.
  • The document parsing and normalization helpers implemented by this SDK.
  • The HTTP client wrapper used to call a configured Cortexa service URL.
  • Build and compiler configuration for the SDK package.
  • Examples that demonstrate SDK usage.

Outside the repository boundary:

  • The @cortexa/contracts package and its ownership of shared domain types.
  • The Cortexa API service that implements /health and /analyze.
  • Any database, object store, search index, message queue, workflow engine, or deployment runtime.
  • Consumer applications and their product workflows.
  • Google API integrations or provider-specific ingestion connectors. Although googleapis is declared as a dependency, no implemented source module currently integrates with Google APIs.

The primary ownership boundary is the package export boundary. Consumers should depend on exported SDK APIs rather than internal file paths. The primary integration boundary is the HTTP service boundary represented by CortexaClient.

High-Level Architecture​

The repository is organized as a small layered SDK:

  • Public package layer: the root SDK entrypoint re-exports the supported modules for consumers.
  • Contract-facing type layer: local exports expose SDK request/response interfaces and re-export shared document types from @cortexa/contracts.
  • Processing layer: processDocument coordinates parsing and normalization.
  • Parsing layer: document parsing adapts a raw document payload into parsed content.
  • Normalization layer: normalization adapts parsed content into a normalized document.
  • Client layer: CortexaClient wraps HTTP calls to the external Cortexa service.

The dependency direction is inward toward contracts and downward through the processing flow. The processor depends on parser and normalizer modules; parser and normalizer depend on contract types. The client depends on SDK-specific input/output interfaces and the HTTP transport library. The external Cortexa service is invoked only through the client abstraction.

The implemented architecture is intentionally thin. It provides a typed SDK facade and a minimal local transformation path, while deeper domain behavior remains outside this package.

Domain Overview​

The repository represents a document ingestion domain with these primary concepts:

  • Raw document: an input document shape owned by @cortexa/contracts.
  • Parsed content: extracted content from a raw document, currently represented by text and tables from the payload.
  • Normalized document: a normalized representation owned by @cortexa/contracts.
  • Cortexa analysis input: a tenant-scoped request shape containing document content and source metadata.
  • Cortexa analysis output: a service response shape indicating success and optional summary or metadata.

These concepts are exposed to help consumers pass document data across the SDK boundary. The SDK does not own the full lifecycle of documents after analysis, nor does it define durable storage semantics for normalized output.

Contracts and Integration Points​

Significant contracts and integration points are:

  • Package exports: the SDK root export is the stable consumer-facing contract.
  • Shared domain types: RawDocument, ParsedContent, and NormalizedDocument come from @cortexa/contracts.
  • SDK HTTP types: CortexaInput and CortexaOutput define the current request and response shapes used by the SDK client.
  • Document processing functions: parseDocument, normalizeDocument, and processDocument form the local transformation contract.
  • HTTP service endpoints: CortexaClient calls GET /health and POST /analyze against the configured base URL.

There are no implemented event contracts, provider adapter interfaces, storage repositories, or runtime plugin systems in the current source. There are also no implemented Zod schemas despite the schema directory and dependency being present.

Infrastructure Responsibilities​

This repository has minimal infrastructure responsibility.

Storage and persistence are outside the SDK. The SDK creates in-memory objects and returns them to the caller; it does not write to a database, object store, filesystem, queue, or index as part of its implemented processing path.

Configuration is limited to package build settings and the baseURL provided to the HTTP client constructor. Environment loading, secrets management, deployment configuration, and service discovery are delegated to consumers or platform infrastructure.

Security responsibility is limited to preserving typed boundaries in SDK code. The current implementation does not add authentication headers, token management, request signing, authorization checks, input sanitization, or runtime validation. Those concerns must be supplied by consuming applications, service infrastructure, or future explicit SDK capabilities.

Orchestration is outside this repository. The SDK exposes callable functions and a client class; it does not schedule work, manage workers, coordinate retries, or own process lifecycle.

Architectural Constraints and Invariants​

The following constraints should remain true unless the architecture is intentionally changed:

  • @cortexa/contracts remains the source of truth for shared Cortexa document contract types.
  • Consumers should import through the SDK package entrypoint rather than internal module paths.
  • SDK code should not duplicate canonical contract definitions owned by @cortexa/contracts.
  • Local processing should preserve a clear flow from raw document to parsed content to normalized document.
  • HTTP service interaction should remain isolated behind client abstractions rather than spread across processing modules.
  • The SDK should not take ownership of persistence, backend analysis, tenancy enforcement, or deployment orchestration.
  • Provider-specific integrations should be introduced as explicit adapters or modules rather than hidden inside generic document processing.
  • Runtime validation, when implemented, should align with shared contracts and should not create conflicting schemas.
  • Build output is generated from TypeScript source; generated distribution artifacts are not architectural source of truth.

Extensibility and Design Principles​

The implementation reflects these design decisions:

  • Thin SDK boundary: the package favors a compact exported surface over embedding platform behavior.
  • Contract reuse: shared document types are imported from the contracts package instead of redefined locally.
  • Pipeline composition: document processing is split into parsing, normalization, and orchestration functions.
  • Transport isolation: external API calls are centralized in a client class configured with a service base URL.
  • Type-first consumption: TypeScript interfaces and declarations are part of the SDK's consumer contract.
  • Consumer-owned runtime policy: authentication, retries, logging, persistence, and orchestration remain outside the implemented SDK core.

These principles support adding behavior without turning the SDK into a backend service or duplicating domain ownership from other Cortexa packages.

Documentation Corpus Map​

This document is the architectural entrypoint for the repository.

Expected documentation roles:

  • /README.md: repository landing page and first-use introduction.
  • /docs/ARCHITECTURE.md: architectural overview, boundaries, responsibilities, and design intent.
  • /docs/REPOSITORY.md: repository organization, folder structure, package organization, and code placement guidance.

At the time this document was generated, /docs/REPOSITORY.md and /README.md are not present in the repository tree. When they are added, this document should reference them for navigation details rather than duplicating their contents.

Guidance for Developers and AI Agents​

Start with this document to understand ownership boundaries before changing code. Use /docs/REPOSITORY.md for folder-level navigation and code placement guidance when that document exists.

Treat @cortexa/contracts as authoritative for shared domain shapes. Before adding or changing SDK-local types that overlap with contract types, verify whether the change belongs in the contracts repository instead.

Keep SDK changes scoped to package responsibilities: exported APIs, client integration, local parsing and normalization helpers, examples, and build configuration. Do not add persistence, service orchestration, backend analysis behavior, or provider-specific integrations without making those responsibilities explicit in the architecture.

When adding externally visible behavior, update this document only if the change alters architectural structure, ownership boundaries, integration contracts, or design direction. Routine feature additions should be documented closer to their usage surface and in repository navigation docs rather than expanding this architectural overview.