# theagenticai/cortexon architecture

> Architecture diagram of the GitHub repository theagenticai/cortexon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theagenticai/cortexon
- Repository: https://github.com/theagenticai/cortexon

## Overview

##### Your C4 Levels
- Context Level: Show CortexON as the primary system surrounded by its external actors and integrations. Include external systems like Google Custom Search, Anthropic, Browserbase, LogFire, and Vault.
- Container Level: Break down CortexON into its major software containers. Based on the file tree and README, identify these containers:
– Backend Engines (found mainly under the “cortex_on” directory) that include core agents (e.g., Web Agent, Code Agent, Planner/Orchestrator, etc.)
– Frontend Application (in the “frontend” directory) built in React/TypeScript.
– TA-Browser Module: A distinct container that handles specialized browser automation tasks (under “ta-browser”).
– Supporting Services (e.g., the Docker Compose configuration which defines how containers interact).
- Component Level: Delve into each container to show the internal components/modules.
– For the “cortex_on” container, illustrate different agents (code_agent, orchestrator_agent, planner_agent, file/web agents) and utilities (executors, markdown browser, etc.) as sub-components. Indicate inter-agent communication.
– For the frontend container, present components like Home (chat interface, code block, terminal block interfaces), Vault UI components, and service integrations that call backend APIs.
– For the ta-browser container, show its core modules responsible for browser-based automation (e.g., browser_agent, critique_agent, explainer_agent, etc.) and its internal server structure.

##### Relationships and Interactions
– From the Frontend container to the Backend container: indicate web requests and API interactions (e.g., FastAPI backend APIs).
– From the Backend’s central orchestrator to individual agents (code, web, planner) highlighting multi-agent collaboration.
– Between the TA-Browser container and the Backend, since they complement each other for browser automation tasks.

##### Architectural Patterns and Technologies
- Microservices/multi-container approach as orchestrated via Docker Compose.
- That the design is modular with clearly demarcated responsibilities among agents.
- Mention technologies: FastAPI for backend, React/TypeScript and TailwindCSS for frontend, Docker for containerization, and various external APIs/integrations.
- The use of a multi-agent system pattern should be clearly highlighted — each specialized agent is a “component” with defined tasks and interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integrations
    GC["Google Custom Search"]:::external
    AN["Anthropic"]:::external
    BB["Browserbase"]:::external
    LF["LogFire"]:::external
    VA["Vault"]:::external

    %% CortexON System Context
    subgraph "CortexON"
        F["Frontend (React/TypeScript UI)"]:::frontend
        B["Backend - CortexON Multi-Agent Core"]:::backend
        T["TA-Browser Automation Module"]:::ta_browser
    end

    %% Frontend Components
    subgraph "Frontend Components"
        F1["Home Component (Chat,Code,Terminal)"]:::frontend_component
        F2["Vault UI Component"]:::frontend_component
    end

    %% Backend Components
    subgraph "Backend Components"
        BA1["Web Agent"]:::agent
        BA2["Code Agent"]:::agent
        BA3["Orchestrator Agent"]:::agent
        BA4["Planner Agent"]:::agent
        BA5["Executor Module"]:::utility
        BA6["Markdown Browser"]:::utility
        BA7["Message Handler"]:::utility
    end

    %% TA-Browser Components
    subgraph "TA-Browser Components"
        TA1["Browser Agent"]:::ta_agent
        TA2["Critique Agent"]:::ta_agent
        TA3["Explainer Agent"]:::ta_agent
        TA4["TA-Browser Server"]:::ta_server
    end

    %% Deployment Configuration
    subgraph "Deployment Configuration"
        DC["Docker Compose"]:::deployment
        DD1["Backend Dockerfile"]:::deployment
        DD2["Frontend Dockerfile"]:::deployment
        DD3["TA-Browser Dockerfile"]:::deployment
    end

    %% Relationships between containers
    F -->|"REST_API" | B
    B -->|"BrowserAuto" | T
    B -->|"ExternalAPI" | GC
    B -->|"ExternalAPI" | AN
    B -->|"ExternalAPI" | BB
    B -->|"Logs" | LF
    B -->|"SecureStorage" | VA

    %% Internal Backend interactions (orchestration)
    BA3 -->|"orchestrates" | BA1
    BA3 -->|"orchestrates" | BA2
    BA3 -->|"orchestrates" | BA4

    %% Map Frontend container to its components
    F --> F1
    F --> F2

    %% (Optional) TA-Browser internal linkage
    TA1 -->|"communicates" | TA4

    %% Click Events for Component Mapping
    click B "https://github.com/theagenticai/cortexon/tree/main/cortex_on"
    click BA1 "https://github.com/theagenticai/cortexon/blob/main/cortex_on/agents/web_surfer.py"
    click BA2 "https://github.com/theagenticai/cortexon/blob/main/cortex_on/agents/code_agent.py"
    click BA3 "https://github.com/theagenticai/cortexon/blob/main/cortex_on/agents/orchestrator_agent.py"
    click BA4 "https://github.com/theagenticai/cortexon/blob/main/cortex_on/agents/planner_agent.py"
    click BA5 "https://github.com/theagenticai/cortexon/tree/main/cortex_on/utils/executors"
    click BA6 "https://github.com/theagenticai/cortexon/tree/main/cortex_on/utils/markdown_browser"
    click F "https://github.com/theagenticai/cortexon/tree/main/frontend"
    click F1 "https://github.com/theagenticai/cortexon/tree/main/frontend/src"
    click F2 "https://github.com/theagenticai/cortexon/tree/main/frontend/src/components/vault"
    click T "https://github.com/theagenticai/cortexon/tree/main/ta-browser"
    click TA1 "https://github.com/theagenticai/cortexon/blob/main/ta-browser/core/agents/browser_agent.py"
    click TA2 "https://github.com/theagenticai/cortexon/blob/main/ta-browser/core/agents/critique_agent.py"
    click TA3 "https://github.com/theagenticai/cortexon/blob/main/ta-browser/core/agents/explainer_agent.py"
    click TA4 "https://github.com/theagenticai/cortexon/blob/main/ta-browser/core/server/server.js"
    click DC "https://github.com/theagenticai/cortexon/blob/main/docker-compose.yaml"
    click DD1 "https://github.com/theagenticai/cortexon/tree/main/cortex_on/Dockerfile"
    click DD2 "https://github.com/theagenticai/cortexon/tree/main/frontend/Dockerfile"
    click DD3 "https://github.com/theagenticai/cortexon/tree/main/ta-browser/Dockerfile"

    %% Styles
    classDef backend fill:#aec6ff,stroke:#000,stroke-width:2px
    classDef frontend fill:#c1e1c5,stroke:#000,stroke-width:2px
    classDef ta_browser fill:#ffcc99,stroke:#000,stroke-width:2px
    classDef agent fill:#f3f3a6,stroke:#000,stroke-width:2px
    classDef utility fill:#ffb6c1,stroke:#000,stroke-width:2px
    classDef frontend_component fill:#d1f7c4,stroke:#000,stroke-width:2px
    classDef ta_agent fill:#fdfd96,stroke:#000,stroke-width:2px
    classDef ta_server fill:#ffdead,stroke:#000,stroke-width:2px
    classDef deployment fill:#e0bbff,stroke:#000,stroke-width:2px
    classDef external fill:#dddddd,stroke:#000,stroke-width:2px
```
