Skip to main content

Architecture

Repository Purpose​

cortexa.connectors is a TypeScript npm workspace for Cortexa connector packages. It exists to isolate provider-specific SDK usage, provider API behavior, and provider-to-Cortexa metadata mapping behind reusable connector libraries.

The repository currently implements a Google Drive connector package. That package adapts Google Drive API v3 operations into Cortexa connector contracts so downstream Cortexa systems can interact with provider files through stable Cortexa data shapes instead of direct provider SDK objects.

This repository is not a runtime application. It does not own user interfaces, product workflows, OAuth consent flows, credential storage, ingestion pipelines, indexing, persistence, document intelligence, deployment infrastructure, or background orchestration. Those responsibilities belong to consuming systems or other Cortexa platform repositories.

Ecosystem Role​

This repository sits at the provider-integration edge of the Cortexa ecosystem.

External consumers are Cortexa applications, services, workers, tools, or orchestration layers that need to list or download external provider files through connector packages.

Upstream dependencies include:

  • External provider APIs, currently Google Drive API v3 through the googleapis SDK.
  • @cortexa/contracts, which defines shared connector contract types used across Cortexa repositories.
  • Runtime provider credentials supplied by callers, currently a Google OAuth access token.

Downstream dependencies are systems that instantiate connector packages, provide credentials and operation options, process returned contract objects, and decide how failures, retries, persistence, indexing, and user-facing outcomes are handled.

Related repositories include:

  • cortexa.contracts, consumed as the shared type-contract boundary.
  • Cortexa application, worker, ingestion, orchestration, or tool repositories that import connector packages from this workspace.

External systems include provider platforms such as Google Drive. This repository integrates with those systems but does not own their availability, permissions model, API semantics, quotas, sharing rules, data retention, or identity lifecycle.

Architectural Responsibilities​

This repository owns provider connector implementation. For the implemented Google Drive package, it owns:

  • Constructing provider API clients from caller-supplied credentials.
  • Exposing a small TypeScript connector API for supported provider operations.
  • Listing Google Drive files and folders.
  • Including files shared with the authenticated user when requested.
  • Downloading Google Drive file content.
  • Mapping Google Drive file metadata into @cortexa/contracts connector file types.
  • Keeping provider SDK request details inside the provider package.

This repository explicitly delegates:

  • Shared contract definition to @cortexa/contracts.
  • OAuth authorization, token acquisition, token refresh, tenant authorization, and credential storage to calling systems.
  • Persistence, indexing, deduplication, scanning, transformation, and downstream processing to consuming Cortexa systems.
  • Scheduling, job orchestration, retry policy, observability policy, and user-facing behavior to consuming applications or infrastructure layers.
  • Provider account permissions, sharing behavior, quota enforcement, and provider data ownership to external provider platforms.

System Boundaries​

Inside the repository boundary:

  • Workspace and package configuration for connector libraries.
  • Provider connector package source code.
  • Provider SDK client construction.
  • Provider operation services.
  • Provider-to-Cortexa contract mapping.
  • Connector-specific option types.
  • Package-local examples used to exercise connector behavior during development.

Outside the repository boundary:

  • Shared Cortexa contract ownership.
  • Consumer application and workflow code.
  • Authentication and authorization flows.
  • Credential lifecycle management.
  • Persistent storage, schema ownership, and infrastructure provisioning.
  • Message queues, background jobs, sync orchestration, and ingestion pipelines.
  • Provider-side implementation, data ownership, and access policy.

The primary integration boundary is the connector package public API. Consumers pass credentials and operation options into connector classes and receive Cortexa contract objects back. Raw provider SDK response objects are implementation details and should not become downstream application contracts.

High-Level Architecture​

The repository is organized as a private npm workspace. Provider connectors are modeled as independent packages under the workspace so provider SDK dependencies and implementation details remain isolated.

The currently implemented package is @cortexa/connectors-google-drive. Its architecture follows a small layered library pattern:

  • Public connector facade: exposes the consumer-facing connector class and public option types.
  • Provider client layer: creates an authenticated Google Drive SDK client from runtime credentials.
  • Service layer: performs provider operations such as listing files, traversing folders, listing shared resources, and downloading content.
  • Mapping layer: converts Google Drive SDK file objects into shared Cortexa connector contract objects.
  • Contract boundary: imports shared Cortexa types from @cortexa/contracts rather than defining repository-local equivalents.

The dependency direction flows from the public connector facade into package-local services, from services into provider clients and mappers, and from mappers into shared contract types. Provider SDK details remain inside the provider package.

Domain Overview​

The repository represents a narrow connector domain:

  • Connector: a provider-specific library object that exposes supported operations against an external system.
  • Provider credential: caller-supplied authentication material used to create a provider client.
  • External file: a provider-owned file or folder identified by provider IDs and metadata.
  • Connector file: the Cortexa contract representation of external file metadata.
  • Downloaded file: the Cortexa contract representation of file metadata plus downloaded payload content.
  • Folder hierarchy: provider parent-child relationships exposed through connector metadata and optional recursive traversal.
  • Shared resource: a provider file shared with the authenticated account and included only when requested by connector options.

The repository does not define the broader Cortexa content, document, tenant, ingestion, search, indexing, or authorization domain. It adapts external provider file concepts into shared connector contracts.

Contracts And Integration Points​

The main implemented package contract is the public API exported by @cortexa/connectors-google-drive.

Implemented interactions include:

  • GoogleDriveConnector construction with a Google OAuth access token supplied by the caller.
  • healthCheck(), which reports basic connector identity and availability at the package boundary.
  • listFiles(options?), which returns ConnectorFile[] from @cortexa/contracts.
  • downloadFile(fileId), which returns DownloadedFile from @cortexa/contracts.
  • ListFilesOptions, which supports parent filtering, recursive folder traversal, and inclusion of files shared with the authenticated user.

External integration points include:

  • Google Drive API v3, reached through the googleapis SDK.
  • Google OAuth access tokens, supplied by callers rather than acquired by this repository.
  • @cortexa/contracts, used as the durable type boundary between connector packages and the rest of the ecosystem.

Provider-specific API responses are treated as internal implementation details. The architectural contract is the Cortexa connector type surface, not the raw provider response shape.

Infrastructure Responsibilities​

This repository has minimal infrastructure ownership.

Storage and persistence are not owned here. Connector operations return in-memory metadata and payload objects to callers. Consuming systems decide whether and where to persist metadata, binary content, sync cursors, audit records, logs, or processing state.

Security responsibilities are limited to accepting runtime credentials and passing them to provider SDK clients. The repository does not store credentials, refresh tokens, issue tokens, authorize users, enforce tenant policy, or manage provider consent.

Configuration is package-level and build-time oriented: TypeScript compiler configuration, npm workspace configuration, package manifests, dependency declarations, and package-local example configuration. Runtime credentials and execution context are supplied by callers.

Orchestration is outside the repository. Connectors perform direct provider calls when invoked; they do not schedule work, coordinate durable retries, publish events, manage queues, or operate background workers.

There is no docs/DATABASE.md in the current repository because the implemented architecture does not own persistence, schema design, or database infrastructure.

Architectural Constraints And Invariants​

The following constraints should remain true as the repository evolves:

  • Connector packages depend on @cortexa/contracts for shared ecosystem types instead of redefining those contracts locally.
  • Public connector APIs return Cortexa contract types, not raw provider SDK objects.
  • Provider SDK types, request construction, and response handling stay inside provider packages.
  • Authentication lifecycle ownership remains outside connector packages unless a deliberate architecture change redefines that boundary.
  • Provider-specific mapping remains explicit enough that consumers do not need to understand provider response shapes.
  • Repository packages remain library packages rather than standalone applications.
  • Persistence, indexing, scheduling, ingestion orchestration, and user-facing workflows remain downstream responsibilities.
  • Provider-specific dependencies stay isolated to the relevant provider package unless there is a clear shared-package boundary.
  • New provider packages should preserve the same consumer-facing contract pattern while keeping provider internals independent.
  • Implemented behavior and documented contracts must stay aligned; planned or unfinished capabilities must be marked as non-implemented when referenced.

Extensibility And Design Principles​

The implemented architecture favors provider-package isolation. The Google Drive package contains its own client construction, services, mappers, public exports, package manifest, and examples. This supports adding other provider packages without coupling them to Google Drive internals or forcing unrelated consumers to depend on Google-specific SDKs.

The architecture also favors contract normalization. Provider metadata is mapped into Cortexa connector contracts before crossing the package boundary. This keeps downstream systems aligned to Cortexa concepts and lets provider implementation details change with less downstream impact.

The public connector class acts as a small facade over package-local services. This gives consumers a compact API while allowing provider operations and mapping behavior to evolve behind that facade.

Credentials are injected by callers. That keeps authentication policy and secret lifecycle management in systems that have tenant, user, deployment, and compliance context.

The workspace structure supports additional provider packages, but only the Google Drive provider is implemented today.

Documentation Corpus Map​

Current repository documentation:

  • /README.md: repository landing page and quick orientation.
  • /docs/ARCHITECTURE.md: architectural source of truth for repository purpose, ecosystem role, responsibilities, boundaries, contracts, constraints, and design principles.
  • /docs/REPOSITORY.md: repository organization source of truth for folder structure, package organization, code placement guidance, and navigation.
  • /packages/google-drive/README.md: package-level documentation surface for the Google Drive connector package. It is currently minimal.

Standard documentation files that are not present:

  • /docs/DATABASE.md: not present because this repository currently owns no persistence or schema architecture.
  • /docs/ECOSYSTEM.md: not present; ecosystem relationships are summarized here and in README.md until a dedicated ecosystem document exists.
  • /references/CORTEXA_PLATFORM.md: not present in this repository.

Use REPOSITORY.md for repository organization, folder structure, package organization, and code placement guidance. Use DATABASE.md if it is added later for persistence architecture, data ownership, and schema organization. Use ECOSYSTEM.md if it is added later for ecosystem capability ownership and platform integration relationships. This architecture document should remain the architectural entrypoint rather than duplicating those documents.

Guidance For Developers And AI Agents​

Start with this document to understand repository purpose, ownership boundaries, and architectural constraints. Use README.md for quick orientation and docs/REPOSITORY.md for navigation and code placement.

When changing this repository, preserve the distinction between connector-library responsibilities and downstream application responsibilities. Do not add persistence, orchestration, authentication lifecycle, indexing, UI, deployment, or product workflow behavior to connector packages unless the repository boundary is intentionally changed and this document is updated.

When adding provider support, keep provider SDK details inside the provider package, expose a deliberate public package API, and map returned data into @cortexa/contracts before it crosses the package boundary.

When updating documentation, keep each document in its lane: architecture here, repository organization in REPOSITORY.md, persistence in DATABASE.md if that document exists, and ecosystem capability ownership in ECOSYSTEM.md if that document exists. Document implemented behavior only, and label planned or unfinished behavior explicitly.