Skip to main content

CORTEXA_PLATFORM.md

Purpose

Cortexa is a modular platform designed to provide reusable infrastructure, contracts, integrations, document processing capabilities, and future intelligence services that can be shared across multiple products, applications, services, and organizations.

Rather than building AI, document, authentication, integration, and knowledge capabilities independently inside every product, Cortexa centralizes these concerns into reusable platform modules with clearly defined ownership boundaries.

The primary objective of the ecosystem is to enable products such as TUASESOR and future vertical applications to consume common platform capabilities while remaining independent from implementation details.

Cortexa is not a single application.

It is a collection of interoperable modules that together form a reusable software platform.

Platform Vision

The long-term vision of Cortexa is to become a programmable intelligence platform capable of:

  • Connecting to external systems.
  • Authenticating and managing external accounts.
  • Ingesting and processing documents.
  • Normalizing business information.
  • Building organizational knowledge.
  • Supporting intelligent retrieval.
  • Powering future AI capabilities.
  • Enabling agent-based automation.

The platform is designed around modularity, separation of concerns, reusable infrastructure, and independent evolution of platform capabilities.

Each module owns a specific responsibility and exposes reusable services that can be consumed by multiple products.

Ecosystem Overview

The Cortexa ecosystem currently contains two categories of modules:

Production Modules​

These modules are implemented, operational, and actively used by systems such as TUASESOR.

  • cortexa.auth
  • cortexa.connectors
  • cortexa.contracts
  • cortexa.sdk

Strategic Platform Modules​

These modules represent the future direction of the platform and are currently under design, architectural planning, or incremental development.

  • cortexa.capabilities
  • cortexa.agents
  • cortexa.knowledge
  • cortexa.cloud

The ecosystem is intentionally structured so that future modules can be added without disrupting existing platform consumers.

Current Platform

cortexa.contracts​

Purpose​

Provides the canonical shared contracts for the entire Cortexa ecosystem.

Responsibilities​

  • Own shared platform schemas.
  • Define runtime validation schemas.
  • Export inferred TypeScript types.
  • Define shared vocabularies and enums.
  • Define document contracts.
  • Define connector contracts.
  • Define event contracts.
  • Define extraction contracts.
  • Define AI-related result contracts.
  • Define common platform primitives.

Dependencies​

The module intentionally minimizes dependencies and acts as a foundational package.

Other Cortexa modules depend on it.

Consumers​

  • cortexa.auth
  • cortexa.connectors
  • cortexa.sdk
  • Future Cortexa modules
  • External products

Platform Role​

This module serves as the contract boundary for the ecosystem and reduces contract drift between independently developed services and applications.

cortexa.auth​

Purpose​

Provides reusable OAuth infrastructure for external account authentication.

Responsibilities​

  • External OAuth account management.
  • Session management.
  • Credential lifecycle handling.
  • Access token refresh.
  • Provider abstraction.
  • Auth orchestration through AuthService.
  • Provider-neutral authentication contracts.

Dependencies​

  • External OAuth providers.
  • Google OAuth implementation.
  • Runtime configuration supplied by host applications.

Consumers​

  • Cortexa applications.
  • Integration services.
  • Products requiring OAuth connectivity.
  • Future connector and automation modules.

Platform Role​

Acts as the authentication foundation for external integrations while isolating provider-specific OAuth complexity from consuming applications.

cortexa.connectors​

Purpose​

Provides provider-specific integration packages for external systems.

Responsibilities​

  • Connector implementations.
  • External API abstraction.
  • Metadata mapping.
  • File access operations.
  • Provider SDK isolation.
  • Translation of external provider data into Cortexa contracts.

Dependencies​

  • External provider APIs.
  • OAuth sessions supplied by consuming applications.
  • Shared contracts from cortexa.contracts.

Consumers​

  • Document ingestion systems.
  • Knowledge systems.
  • Processing pipelines.
  • Future agent systems.
  • Vertical products.

Platform Role​

Represents the integration boundary between Cortexa and external content providers.

Current implementation focuses on Google Drive.

Future providers can be added through additional connector packages.

cortexa.sdk​

Purpose​

Provides the primary developer-facing SDK for document ingestion and normalization.

Responsibilities​

  • Document processing.
  • Parsing workflows.
  • Content normalization.
  • Client-side Cortexa integrations.
  • HTTP access to Cortexa services.
  • Shared type exports.
  • Developer integration surface.

Dependencies​

  • cortexa.contracts
  • Cortexa HTTP services
  • Internal parsers and normalizers

Consumers​

  • Applications
  • Ingestion jobs
  • Developer tooling
  • Automation systems
  • External products

Platform Role​

Acts as the primary entry point for applications that need to interact with Cortexa document-processing capabilities.

Future Platform

The following modules are part of the architectural direction of the ecosystem.

Their inclusion reflects platform intent rather than currently documented production readiness.

cortexa.knowledge​

Intended Purpose​

Become the semantic knowledge layer of the ecosystem.

Planned Responsibilities​

  • Knowledge indexing.
  • Semantic retrieval.
  • Hybrid search.
  • Chunk management.
  • Metadata-aware retrieval.
  • Context ranking.
  • Workspace knowledge isolation.
  • Retrieval APIs for AI systems.

Relationship With Existing Modules​

Consumes:

  • cortexa.sdk
  • cortexa.connectors
  • cortexa.contracts

Provides:

  • Retrieval capabilities for agents and AI systems.

cortexa.capabilities​

Intended Purpose​

Provide reusable business and AI capabilities that can be consumed across products.

Planned Responsibilities​

  • Reusable platform services.
  • Domain-independent intelligence functions.
  • Capability orchestration.
  • Shared AI workflows.
  • Cross-product reusable features.

Relationship With Existing Modules​

Expected to consume:

  • Knowledge services.
  • Connectors.
  • Contracts.
  • Future cloud infrastructure.

cortexa.agents​

Intended Purpose​

Provide autonomous and semi-autonomous agent infrastructure.

Planned Responsibilities​

  • Agent execution.
  • Multi-step orchestration.
  • Tool usage.
  • Workflow automation.
  • Human-in-the-loop operations.
  • Knowledge consumption.
  • Capability composition.

Relationship With Existing Modules​

Expected to consume:

  • cortexa.knowledge
  • cortexa.capabilities
  • cortexa.connectors
  • cortexa.auth

cortexa.cloud​

Intended Purpose​

Provide platform infrastructure and cloud-native operational services.

Planned Responsibilities​

  • Platform hosting abstractions.
  • Infrastructure services.
  • Runtime management.
  • Deployment foundations.
  • Platform observability.
  • Shared operational capabilities.

Relationship With Existing Modules​

Expected to become the operational foundation supporting higher-level platform services.

Module Relationships

The current ecosystem follows a layered dependency model.

External Products
        |
        v
   cortexa.sdk
        |
        v
cortexa.connectors
        |
        v
   cortexa.auth

All Modules
        |
        v
cortexa.contracts

Future architecture is expected to evolve toward:

Products
   |
   v
Agents
   |
   v
Capabilities
   |
   v
Knowledge
   |
   v
SDK / Connectors / Auth
   |
   v
Contracts

Key principles:

  • Higher layers consume lower layers.
  • Lower layers never depend on higher layers.
  • Shared contracts remain foundational.
  • Integrations remain isolated behind connectors.

Shared Platform Capabilities

Current reusable platform capabilities include:

Shared Contracts​

Provided by:

  • cortexa.contracts

Includes:

  • Documents
  • Events
  • Connectors
  • Extraction results
  • AI-related payloads
  • Common primitives

OAuth Infrastructure​

Provided by:

  • cortexa.auth

Includes:

  • External account connection
  • Session retrieval
  • Session refresh
  • Provider abstraction

Connector Infrastructure​

Provided by:

  • cortexa.connectors

Includes:

  • File listing
  • File download
  • Metadata mapping
  • Provider abstraction

Document Processing​

Provided by:

  • cortexa.sdk

Includes:

  • Parsing
  • Normalization
  • Analysis service access

External Product Integration Model

Products such as TUASESOR consume Cortexa modules as reusable platform components.

Typical integration flow:

Product
   |
   v
SDK
   |
   v
Connectors
   |
   v
External Systems

Authentication flow:

Product
   |
   v
Auth
   |
   v
OAuth Provider

Contract flow:

All Modules
   |
   v
Contracts

This architecture allows products to focus on business workflows while delegating platform concerns to Cortexa modules.

Ownership Boundaries

cortexa.contracts​

Owns:

  • Shared schemas
  • Shared types
  • Shared payload definitions

Does Not Own:

  • Business logic
  • APIs
  • Storage
  • Integrations

cortexa.auth​

Owns:

  • OAuth orchestration
  • External account lifecycle
  • Session management

Does Not Own:

  • Product users
  • Authorization policies
  • UI
  • Persistence implementations

cortexa.connectors​

Owns:

  • Provider integrations
  • Metadata mapping
  • Connector APIs

Does Not Own:

  • Authentication lifecycle
  • Ingestion workflows
  • Persistence
  • Indexing

cortexa.sdk​

Owns:

  • SDK interfaces
  • Document processing helpers
  • HTTP client access

Does Not Own:

  • Backend analysis services
  • Storage
  • Platform orchestration

Future Modules​

Future modules should own:

  • Knowledge
  • Capabilities
  • Agent orchestration
  • Platform infrastructure

while preserving existing ownership boundaries.

Architectural Principles

The current ecosystem consistently reflects the following principles:

Modular Design​

Every module owns a specific responsibility.

Separation of Concerns​

Authentication, integrations, contracts, and SDK functionality are isolated.

Reusable Infrastructure​

Modules are designed to be consumed by multiple products.

Contract-First Architecture​

Shared contracts define communication boundaries.

Provider Isolation​

External provider complexity is hidden behind adapters and connectors.

Consumer Independence​

Applications depend on stable Cortexa APIs rather than provider SDKs.

Incremental Evolution​

Future capabilities can be added without restructuring existing modules.

Extensibility Strategy

The platform is intentionally designed for expansion.

New modules can be introduced when they:

  • Own a distinct responsibility.
  • Expose reusable platform services.
  • Maintain contract compatibility.
  • Respect existing ownership boundaries.

Examples include:

  • Additional connectors.
  • New AI capabilities.
  • Knowledge engines.
  • Agent runtimes.
  • Cloud services.
  • Observability modules.
  • Audit modules.

Ecosystem Evolution

Current State:

Contracts
Auth
Connectors
SDK

Intermediate State:

Contracts
Auth
Connectors
SDK
Knowledge
Capabilities

Long-Term State:

Contracts
Auth
Connectors
SDK
Knowledge
Capabilities
Agents
Cloud

The architectural trajectory moves from reusable integration infrastructure toward a complete programmable intelligence platform.

Architectural Observations

Strengths​

  • Clear separation of responsibilities.
  • Strong contract-first foundation.
  • Low coupling between modules.
  • Reusable integration architecture.
  • Future-ready layering.
  • Good alignment for multi-product ecosystems.

Architectural Patterns​

  • Layered architecture.
  • Package-oriented modularity.
  • Adapter pattern for providers.
  • Shared contract model.
  • SDK boundary pattern.
  • Provider abstraction pattern.

Current Limitations​

  • Google is currently the primary implemented provider for both authentication and connectors.
  • Knowledge infrastructure is not yet implemented as a production module.
  • Agent infrastructure remains conceptual.
  • Cloud platform abstractions remain future-facing.

Strategic Advantage​

The ecosystem is already structured around reusable platform components rather than product-specific implementations, enabling future products to leverage shared infrastructure instead of rebuilding core capabilities.

This positions Cortexa to evolve from a collection of reusable technical modules into a unified intelligence platform capable of powering multiple products, workflows, integrations, and AI-driven systems.