How ashwathsingh/cortex works
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: main.py API router · ingest.py GitHub ingestion · neo4j_driver.py Knowledge graph · auth.py Authentication
Components 27
Web client
- Workspace UI
apps/web/src/app/workspaces/[workspaceId]/page.tsx - Ingestion form
apps/web/src/components/ingest/repo-ingest-form.tsx - Graph Explorer
apps/web/src/components/graph/graph-view.tsx - Review queue
apps/web/src/components/review/review-queue.tsx - Source inventory
apps/web/src/components/sources/source-inventory.tsx - Assistant UI
apps/web/src/components/workspaces/assistant-composer.tsx - Sign-in UI
apps/web/src/components/auth/login-form.tsx
API and domain
- API router
backend/app/main.py - Authentication
backend/app/api/auth.py - Request authorization
backend/app/api/deps.py - Security primitives
backend/app/security.py - Workspace management
backend/app/services/workspaces.py - Roles and permissions
backend/app/services/roles.py - GitHub ingestion
backend/app/api/ingest.py - Artifact mapper
backend/app/github/mapper.py - Source sync state
backend/app/services/data_sources.py - Graph API
backend/app/api/graph.py - Graph queries
backend/app/graph/queries.py - Assistant API
backend/app/api/assistant.py - Assistant service
backend/app/services/assistant.py - Graph agents
backend/app
Persistence
- Relational store
backend/app/db/postgres.py - Knowledge graph
backend/app/db/neo4j_driver.py
External services
- GitHub client
backend/app/github/client.py
Other components
- Team member
- GitHub
- Slack and PRDs
Connections 31
- Team member → Sign-in UI: signs in
- Sign-in UI → API router: calls API
- API router → Authentication: routes auth
backend/app/main.py - Authentication → Security primitives: uses tokens
backend/app/api/auth.py - Authentication → Relational store: stores sessions
backend/app/api/auth.py - API router → GitHub ingestion: routes ingest
backend/app/main.py - Ingestion form → GitHub ingestion: submits repository
- GitHub ingestion → Request authorization: authorizes workspace
backend/app/api/ingest.py - GitHub ingestion → GitHub client: fetches artifacts
backend/app/api/ingest.py - GitHub client → GitHub: requests data
backend/app/github/client.py - GitHub ingestion → Artifact mapper: writes artifacts
backend/app/api/ingest.py - GitHub ingestion → Source sync state: records sync
backend/app/api/ingest.py - Source sync state → Relational store: persists status
backend/app/services/data_sources.py - Artifact mapper → Knowledge graph: writes graph
- API router → Graph API: routes graph
backend/app/main.py - Graph API → Graph queries: fetches graph
backend/app/api/graph.py - Graph queries → Knowledge graph: queries graph
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
backend/app/main.py - Assistant UI → Assistant API: asks questions
- Assistant API → Assistant service: delegates answers
backend/app/api/assistant.py - Assistant service → Knowledge graph: retrieves context
- API router → Workspace management: routes workspace actions
backend/app/main.py - API router → Roles and permissions: routes role actions
backend/app/main.py - Request authorization → Roles and permissions: checks permissions
backend/app/api/deps.py - Slack and PRDs → GitHub ingestion: planned ingestion
- Graph agents → Knowledge graph: planned graph analysis
backend/app/api/ingest.py - Graph agents → Review queue: proposes review