# ashwathsingh/cortex architecture

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

- Interactive diagram: https://gitdiagram.com/ashwathsingh/cortex
- Repository: https://github.com/ashwathsingh/cortex

## Overview

Cortex is an auditable project-memory product: it ingests GitHub artifacts into a workspace-scoped knowledge graph, exposes source provenance through an Explorer and review UI, and offers an assistant interface. The graph preserves auth, workspace permissions, source-sync tracking, and graph storage as distinct internal layers. README capabilities that are explicitly planned are shown as planned branches, not as implemented runtime stages. Some component paths are exact directories because their implementation was not sampled; relationship evidence is limited to the README and SOURCE INDEX references.

Main entry points: [`backend/app/main.py`](https://github.com/ashwathsingh/cortex/blob/main/backend/app/main.py) (API router), [`backend/app/api/ingest.py`](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/ingest.py) (GitHub ingestion), [`backend/app/db/neo4j_driver.py`](https://github.com/ashwathsingh/cortex/blob/main/backend/app/db/neo4j_driver.py) (Knowledge graph), [`backend/app/api/auth.py`](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_workspace_ui["Workspace UI<br/>[page.tsx]"]
  node_ingest_ui["Ingestion form"]
  node_graph_ui["Graph Explorer<br/>[graph-view.tsx]"]
  node_review_ui["Review queue<br/>[review-queue.tsx]"]
  node_sources_ui["Source inventory"]
  node_assistant_ui["Assistant UI"]
  node_auth_ui["Sign-in UI<br/>[login-form.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_app["API router<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_request_auth["Request authorization<br/>[deps.py]"]
  node_security["Security primitives<br/>[security.py]"]
  node_workspace_domain["Workspace management<br/>[workspaces.py]"]
  node_roles["Roles and permissions<br/>[roles.py]"]
  node_ingest_api["GitHub ingestion<br/>[ingest.py]"]
  node_mapper["Artifact mapper<br/>[mapper.py]"]
  node_source_state["Source sync state<br/>[data_sources.py]"]
  node_graph_api["Graph API<br/>[graph.py]"]
  node_graph_queries["Graph queries<br/>[queries.py]"]
  node_assistant_api["Assistant API<br/>[assistant.py]"]
  node_assistant_service["Assistant service<br/>[assistant.py]"]
  node_agents["Graph agents"]
end

subgraph group_stores["Persistence"]
  node_postgres[("Relational store<br/>[postgres.py]")]
  node_neo4j[("Knowledge graph<br/>[neo4j_driver.py]")]
end

subgraph group_external["External services"]
  node_github_client["GitHub client<br/>[client.py]"]
end

node_user(("Team member"))
node_github{{"GitHub"}}
node_planned_sources{{"Slack and PRDs"}}

node_user -->|"signs in"| node_auth_ui
node_auth_ui -->|"calls API"| node_api_app
node_api_app -->|"routes auth"| node_auth
node_auth -->|"uses tokens"| node_security
node_auth -->|"stores sessions"| node_postgres
node_api_app -->|"routes ingest"| node_ingest_api
node_ingest_ui -->|"submits repository"| node_ingest_api
node_ingest_api -->|"authorizes workspace"| node_request_auth
node_ingest_api -->|"fetches artifacts"| node_github_client
node_github_client -->|"requests data"| node_github
node_ingest_api -->|"writes artifacts"| node_mapper
node_ingest_api -->|"records sync"| node_source_state
node_source_state -->|"persists status"| node_postgres
node_mapper -->|"writes graph"| node_neo4j
node_api_app -->|"routes graph"| node_graph_api
node_graph_api -->|"fetches graph"| node_graph_queries
node_graph_queries -->|"queries graph"| node_neo4j
node_graph_ui -->|"loads graph"| node_graph_api
node_sources_ui -->|"views sources"| node_api_app
node_review_ui -.->|"reviews proposals"| node_api_app
node_workspace_ui -->|"uses workspace"| node_api_app
node_api_app -->|"routes assistant"| node_assistant_api
node_assistant_ui -->|"asks questions"| node_assistant_api
node_assistant_api -->|"delegates answers"| node_assistant_service
node_assistant_service -.->|"retrieves context"| node_neo4j
node_api_app -->|"routes workspace actions"| node_workspace_domain
node_api_app -->|"routes role actions"| node_roles
node_request_auth -->|"checks permissions"| node_roles
node_planned_sources -.->|"planned ingestion"| node_ingest_api
node_agents -.->|"planned graph analysis"| node_neo4j
node_agents -.->|"proposes review"| node_review_ui

click node_workspace_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/app/workspaces/%5BworkspaceId%5D/page.tsx"
click node_ingest_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/ingest/repo-ingest-form.tsx"
click node_graph_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/graph/graph-view.tsx"
click node_review_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/review/review-queue.tsx"
click node_sources_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/sources/source-inventory.tsx"
click node_assistant_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/workspaces/assistant-composer.tsx"
click node_auth_ui "https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/auth/login-form.tsx"
click node_api_app "https://github.com/ashwathsingh/cortex/blob/main/backend/app/main.py"
click node_auth "https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/auth.py"
click node_request_auth "https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/deps.py"
click node_security "https://github.com/ashwathsingh/cortex/blob/main/backend/app/security.py"
click node_workspace_domain "https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/workspaces.py"
click node_roles "https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/roles.py"
click node_ingest_api "https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/ingest.py"
click node_github_client "https://github.com/ashwathsingh/cortex/blob/main/backend/app/github/client.py"
click node_mapper "https://github.com/ashwathsingh/cortex/blob/main/backend/app/github/mapper.py"
click node_source_state "https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/data_sources.py"
click node_graph_api "https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/graph.py"
click node_graph_queries "https://github.com/ashwathsingh/cortex/blob/main/backend/app/graph/queries.py"
click node_assistant_api "https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/assistant.py"
click node_assistant_service "https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/assistant.py"
click node_postgres "https://github.com/ashwathsingh/cortex/blob/main/backend/app/db/postgres.py"
click node_neo4j "https://github.com/ashwathsingh/cortex/blob/main/backend/app/db/neo4j_driver.py"
click node_agents "https://github.com/ashwathsingh/cortex/tree/main/backend/app"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workspace_ui,node_ingest_ui,node_graph_ui,node_review_ui,node_sources_ui,node_assistant_ui,node_auth_ui toneBlue
class node_api_app,node_auth,node_request_auth,node_security,node_workspace_domain,node_roles,node_ingest_api,node_mapper,node_source_state,node_graph_api,node_graph_queries,node_assistant_api,node_assistant_service,node_agents toneAmber
class node_postgres,node_neo4j toneMint
class node_github_client toneRose
class node_user,node_github,node_planned_sources toneIndigo
```

## Components

### Web client

- [Workspace UI](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/app/workspaces/%5BworkspaceId%5D/page.tsx): `apps/web/src/app/workspaces/[workspaceId]/page.tsx`
- [Ingestion form](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/ingest/repo-ingest-form.tsx): `apps/web/src/components/ingest/repo-ingest-form.tsx`
- [Graph Explorer](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/graph/graph-view.tsx): `apps/web/src/components/graph/graph-view.tsx`
- [Review queue](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/review/review-queue.tsx): `apps/web/src/components/review/review-queue.tsx`
- [Source inventory](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/sources/source-inventory.tsx): `apps/web/src/components/sources/source-inventory.tsx`
- [Assistant UI](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/workspaces/assistant-composer.tsx): `apps/web/src/components/workspaces/assistant-composer.tsx`
- [Sign-in UI](https://github.com/ashwathsingh/cortex/blob/main/apps/web/src/components/auth/login-form.tsx): `apps/web/src/components/auth/login-form.tsx`

### API and domain

- [API router](https://github.com/ashwathsingh/cortex/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Request authorization](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Security primitives](https://github.com/ashwathsingh/cortex/blob/main/backend/app/security.py): `backend/app/security.py`
- [Workspace management](https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/workspaces.py): `backend/app/services/workspaces.py`
- [Roles and permissions](https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/roles.py): `backend/app/services/roles.py`
- [GitHub ingestion](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/ingest.py): `backend/app/api/ingest.py`
- [Artifact mapper](https://github.com/ashwathsingh/cortex/blob/main/backend/app/github/mapper.py): `backend/app/github/mapper.py`
- [Source sync state](https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/data_sources.py): `backend/app/services/data_sources.py`
- [Graph API](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Graph queries](https://github.com/ashwathsingh/cortex/blob/main/backend/app/graph/queries.py): `backend/app/graph/queries.py`
- [Assistant API](https://github.com/ashwathsingh/cortex/blob/main/backend/app/api/assistant.py): `backend/app/api/assistant.py`
- [Assistant service](https://github.com/ashwathsingh/cortex/blob/main/backend/app/services/assistant.py): `backend/app/services/assistant.py`
- [Graph agents](https://github.com/ashwathsingh/cortex/tree/main/backend/app): `backend/app`

### Persistence

- [Relational store](https://github.com/ashwathsingh/cortex/blob/main/backend/app/db/postgres.py): `backend/app/db/postgres.py`
- [Knowledge graph](https://github.com/ashwathsingh/cortex/blob/main/backend/app/db/neo4j_driver.py): `backend/app/db/neo4j_driver.py`

### External services

- [GitHub client](https://github.com/ashwathsingh/cortex/blob/main/backend/app/github/client.py): `backend/app/github/client.py`

### Other components

- **Team member**
- **GitHub**
- **Slack and PRDs**

## Connections

- Team member → Sign-in UI: signs in
- Sign-in UI → API router: calls API
- API router → Authentication: routes auth (evidence: `backend/app/main.py`)
- Authentication → Security primitives: uses tokens (evidence: `backend/app/api/auth.py`)
- Authentication → Relational store: stores sessions (evidence: `backend/app/api/auth.py`)
- API router → GitHub ingestion: routes ingest (evidence: `backend/app/main.py`)
- Ingestion form → GitHub ingestion: submits repository
- GitHub ingestion → Request authorization: authorizes workspace (evidence: `backend/app/api/ingest.py`)
- GitHub ingestion → GitHub client: fetches artifacts (evidence: `backend/app/api/ingest.py`)
- GitHub client → GitHub: requests data (evidence: `backend/app/github/client.py`)
- GitHub ingestion → Artifact mapper: writes artifacts (evidence: `backend/app/api/ingest.py`)
- GitHub ingestion → Source sync state: records sync (evidence: `backend/app/api/ingest.py`)
- Source sync state → Relational store: persists status (evidence: `backend/app/services/data_sources.py`)
- Artifact mapper → Knowledge graph: writes graph
- API router → Graph API: routes graph (evidence: `backend/app/main.py`)
- Graph API → Graph queries: fetches graph (evidence: `backend/app/api/graph.py`)
- Graph queries → Knowledge graph: queries graph (evidence: `backend/app/graph/queries.py`)
- Graph Explorer → Graph API: loads graph
- Source inventory → API router: views sources
- Review queue → API router: reviews proposals
- Workspace UI → API router: uses workspace
- API router → Assistant API: routes assistant (evidence: `backend/app/main.py`)
- Assistant UI → Assistant API: asks questions
- Assistant API → Assistant service: delegates answers (evidence: `backend/app/api/assistant.py`)
- Assistant service → Knowledge graph: retrieves context
- API router → Workspace management: routes workspace actions (evidence: `backend/app/main.py`)
- API router → Roles and permissions: routes role actions (evidence: `backend/app/main.py`)
- Request authorization → Roles and permissions: checks permissions (evidence: `backend/app/api/deps.py`)
- Slack and PRDs → GitHub ingestion: planned ingestion
- Graph agents → Knowledge graph: planned graph analysis (evidence: `backend/app/api/ingest.py`)
- Graph agents → Review queue: proposes review