# jmurarka/athena architecture

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

- Interactive diagram: https://gitdiagram.com/jmurarka/athena
- Repository: https://github.com/jmurarka/athena

## Overview

ATHENA turns a user’s product problem into a persisted planning workspace: a project request queues background analysis, the LangGraph pipeline generates product, market, architecture, feasibility, validation, and roadmap outputs, and the API exposes project state and workspace data. The frontend provides project, page, and canvas views; the README describes the overall web/API pairing, but the sampled frontend source does not establish specific component-to-route calls. Pipeline and stage links are supported by its excerpt and the documented DAG; unsampled route internals are represented conservatively.

Main entry points: [`backend/app/graph/pipeline.py`](https://github.com/jmurarka/athena/blob/main/backend/app/graph/pipeline.py) (Planning Pipeline), [`frontend/app/project/[id]/[pageType]/page.tsx`](https://github.com/jmurarka/athena/blob/main/frontend/app/project/%5Bid%5D/%5BpageType%5D/page.tsx) (Workspace Pages), [`backend/app/api/routes/projects.py`](https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/projects.py) (Project API), [`backend/app/agents/base_agent.py`](https://github.com/jmurarka/athena/blob/main/backend/app/agents/base_agent.py) (Agent Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Workspace UI"]
  node_web_workspace["Workspace Pages<br/>[page.tsx]"]
  node_project_dashboard["Project Dashboard<br/>[page.tsx]"]
  node_project_sidebar["Project Sidebar"]
  node_middle_workspace["Plan Workspace"]
  node_flow_canvas["Architecture Canvas"]
  node_api_client["API Client<br/>[api.ts]"]
end

subgraph group_api["API and Projects"]
  node_projects_api["Project API<br/>[projects.py]"]
  node_canvas_api["Canvas Routes<br/>[canvas.py]"]
  node_pages_api["Page Routes<br/>[pages.py]"]
  node_athena_api["Graph Routes<br/>[athena_graph.py]"]
end

subgraph group_execution["Background Orchestration"]
  node_worker_task["Pipeline Task<br/>[tasks.py]"]
  node_pipeline["Planning Pipeline<br/>[pipeline.py]"]
end

subgraph group_planning["Planning and Analysis"]
  node_base_agent["Agent Runtime<br/>[base_agent.py]"]
  node_problem_analysis["Problem Analysis"]
  node_product_agent["Product Planning<br/>[product_agent.py]"]
  node_market_research["Market Research<br/>[market_agent.py]"]
  node_system_design["System Design"]
  node_feasibility["Feasibility Review"]
  node_validation["Plan Validation"]
  node_roadmap["Roadmap Planning<br/>[roadmap_agent.py]"]
  node_rag["Research Retrieval<br/>[rag_service.py]"]
end

subgraph group_storage["Persistence"]
  node_project_records[("Project Records<br/>[project.py]")]
  node_workspace_records[("Pages and Canvas<br/>[page.py]")]
  node_plan_graph_records[("Plan Graph Data<br/>[graph_models.py]")]
  node_run_records[("Agent Run Records<br/>[agent_run.py]")]
  node_database[("SQL Database<br/>[db.py]")]
end

node_planner_user(("Planner"))

node_planner_user -->|"uses"| node_web_workspace
node_web_workspace -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_projects_api
node_project_dashboard -.->|"shows projects"| node_project_sidebar
node_web_workspace -.->|"renders"| node_middle_workspace
node_web_workspace -.->|"shows canvas"| node_flow_canvas
node_planner_user -->|"creates project"| node_projects_api
node_projects_api -->|"creates and queries"| node_project_records
node_projects_api -->|"queues analysis"| node_worker_task
node_worker_task -->|"invokes"| node_pipeline
node_pipeline -->|"runs"| node_problem_analysis
node_pipeline -->|"runs"| node_product_agent
node_pipeline -->|"runs"| node_market_research
node_pipeline -->|"runs"| node_system_design
node_pipeline -->|"runs"| node_feasibility
node_pipeline -->|"runs"| node_validation
node_pipeline -->|"runs"| node_roadmap
node_problem_analysis -->|"extends"| node_base_agent
node_product_agent -->|"extends"| node_base_agent
node_system_design -->|"extends"| node_base_agent
node_validation -->|"extends"| node_base_agent
node_pipeline -->|"updates"| node_project_records
node_pipeline -->|"stores outputs"| node_workspace_records
node_pipeline -->|"stores plan entities"| node_plan_graph_records
node_pipeline -->|"tracks stages"| node_run_records
node_project_records -->|"persists in"| node_database
node_workspace_records -->|"persists in"| node_database
node_plan_graph_records -->|"persists in"| node_database
node_run_records -->|"persists in"| node_database

click node_web_workspace "https://github.com/jmurarka/athena/blob/main/frontend/app/project/%5Bid%5D/%5BpageType%5D/page.tsx"
click node_project_dashboard "https://github.com/jmurarka/athena/blob/main/frontend/app/dashboard/page.tsx"
click node_project_sidebar "https://github.com/jmurarka/athena/blob/main/frontend/app/components/SidebarProjects.tsx"
click node_middle_workspace "https://github.com/jmurarka/athena/blob/main/frontend/app/components/MiddleWorkspace.tsx"
click node_flow_canvas "https://github.com/jmurarka/athena/blob/main/frontend/app/components/FlowchartCanvas.tsx"
click node_api_client "https://github.com/jmurarka/athena/blob/main/frontend/lib/api.ts"
click node_projects_api "https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/projects.py"
click node_canvas_api "https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/canvas.py"
click node_pages_api "https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/pages.py"
click node_athena_api "https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/athena_graph.py"
click node_worker_task "https://github.com/jmurarka/athena/blob/main/backend/app/workers/tasks.py"
click node_pipeline "https://github.com/jmurarka/athena/blob/main/backend/app/graph/pipeline.py"
click node_base_agent "https://github.com/jmurarka/athena/blob/main/backend/app/agents/base_agent.py"
click node_problem_analysis "https://github.com/jmurarka/athena/blob/main/backend/app/agents/problem_analysis_agent.py"
click node_product_agent "https://github.com/jmurarka/athena/blob/main/backend/app/agents/product_agent.py"
click node_market_research "https://github.com/jmurarka/athena/blob/main/backend/app/agents/market_agent.py"
click node_system_design "https://github.com/jmurarka/athena/blob/main/backend/app/agents/system_design_agent.py"
click node_feasibility "https://github.com/jmurarka/athena/blob/main/backend/app/agents/feasibility_agent.py"
click node_validation "https://github.com/jmurarka/athena/blob/main/backend/app/agents/validation_engine.py"
click node_roadmap "https://github.com/jmurarka/athena/blob/main/backend/app/agents/roadmap_agent.py"
click node_rag "https://github.com/jmurarka/athena/blob/main/backend/app/core/rag_service.py"
click node_project_records "https://github.com/jmurarka/athena/blob/main/backend/app/models/project.py"
click node_workspace_records "https://github.com/jmurarka/athena/blob/main/backend/app/models/page.py"
click node_plan_graph_records "https://github.com/jmurarka/athena/blob/main/backend/app/models/graph_models.py"
click node_run_records "https://github.com/jmurarka/athena/blob/main/backend/app/models/agent_run.py"
click node_database "https://github.com/jmurarka/athena/blob/main/backend/app/core/db.py"

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_web_workspace,node_project_dashboard,node_project_sidebar,node_middle_workspace,node_flow_canvas,node_api_client toneBlue
class node_projects_api,node_canvas_api,node_pages_api,node_athena_api toneAmber
class node_worker_task,node_pipeline toneMint
class node_base_agent,node_problem_analysis,node_product_agent,node_market_research,node_system_design,node_feasibility,node_validation,node_roadmap,node_rag toneRose
class node_project_records,node_workspace_records,node_plan_graph_records,node_run_records,node_database,node_planner_user toneIndigo
```

## Components

### Workspace UI

- [Workspace Pages](https://github.com/jmurarka/athena/blob/main/frontend/app/project/%5Bid%5D/%5BpageType%5D/page.tsx): `frontend/app/project/[id]/[pageType]/page.tsx`
- [Project Dashboard](https://github.com/jmurarka/athena/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Project Sidebar](https://github.com/jmurarka/athena/blob/main/frontend/app/components/SidebarProjects.tsx): `frontend/app/components/SidebarProjects.tsx`
- [Plan Workspace](https://github.com/jmurarka/athena/blob/main/frontend/app/components/MiddleWorkspace.tsx): `frontend/app/components/MiddleWorkspace.tsx`
- [Architecture Canvas](https://github.com/jmurarka/athena/blob/main/frontend/app/components/FlowchartCanvas.tsx): `frontend/app/components/FlowchartCanvas.tsx`
- [API Client](https://github.com/jmurarka/athena/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and Projects

- [Project API](https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/projects.py): `backend/app/api/routes/projects.py`
- [Canvas Routes](https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/canvas.py): `backend/app/api/routes/canvas.py`
- [Page Routes](https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/pages.py): `backend/app/api/routes/pages.py`
- [Graph Routes](https://github.com/jmurarka/athena/blob/main/backend/app/api/routes/athena_graph.py): `backend/app/api/routes/athena_graph.py`

### Background Orchestration

- [Pipeline Task](https://github.com/jmurarka/athena/blob/main/backend/app/workers/tasks.py): `backend/app/workers/tasks.py`
- [Planning Pipeline](https://github.com/jmurarka/athena/blob/main/backend/app/graph/pipeline.py): `backend/app/graph/pipeline.py`

### Planning and Analysis

- [Agent Runtime](https://github.com/jmurarka/athena/blob/main/backend/app/agents/base_agent.py): `backend/app/agents/base_agent.py`
- [Problem Analysis](https://github.com/jmurarka/athena/blob/main/backend/app/agents/problem_analysis_agent.py): `backend/app/agents/problem_analysis_agent.py`
- [Product Planning](https://github.com/jmurarka/athena/blob/main/backend/app/agents/product_agent.py): `backend/app/agents/product_agent.py`
- [Market Research](https://github.com/jmurarka/athena/blob/main/backend/app/agents/market_agent.py): `backend/app/agents/market_agent.py`
- [System Design](https://github.com/jmurarka/athena/blob/main/backend/app/agents/system_design_agent.py): `backend/app/agents/system_design_agent.py`
- [Feasibility Review](https://github.com/jmurarka/athena/blob/main/backend/app/agents/feasibility_agent.py): `backend/app/agents/feasibility_agent.py`
- [Plan Validation](https://github.com/jmurarka/athena/blob/main/backend/app/agents/validation_engine.py): `backend/app/agents/validation_engine.py`
- [Roadmap Planning](https://github.com/jmurarka/athena/blob/main/backend/app/agents/roadmap_agent.py): `backend/app/agents/roadmap_agent.py`
- [Research Retrieval](https://github.com/jmurarka/athena/blob/main/backend/app/core/rag_service.py): `backend/app/core/rag_service.py`

### Persistence

- [Project Records](https://github.com/jmurarka/athena/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [Pages and Canvas](https://github.com/jmurarka/athena/blob/main/backend/app/models/page.py): `backend/app/models/page.py`
- [Plan Graph Data](https://github.com/jmurarka/athena/blob/main/backend/app/models/graph_models.py): `backend/app/models/graph_models.py`
- [Agent Run Records](https://github.com/jmurarka/athena/blob/main/backend/app/models/agent_run.py): `backend/app/models/agent_run.py`
- [SQL Database](https://github.com/jmurarka/athena/blob/main/backend/app/core/db.py): `backend/app/core/db.py`

### Other components

- **Planner**

## Connections

- Planner → Workspace Pages: uses
- Workspace Pages → API Client: requests data
- API Client → Project API: calls API
- Project Dashboard → Project Sidebar: shows projects
- Workspace Pages → Plan Workspace: renders
- Workspace Pages → Architecture Canvas: shows canvas
- Planner → Project API: creates project
- Project API → Project Records: creates and queries (evidence: `backend/app/api/routes/projects.py`)
- Project API → Pipeline Task: queues analysis (evidence: `backend/app/api/routes/projects.py`)
- Pipeline Task → Planning Pipeline: invokes (evidence: `backend/app/workers/tasks.py`)
- Planning Pipeline → Problem Analysis: runs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Product Planning: runs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Market Research: runs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → System Design: runs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Feasibility Review: runs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Plan Validation: runs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Roadmap Planning: runs (evidence: `backend/app/graph/pipeline.py`)
- Problem Analysis → Agent Runtime: extends (evidence: `backend/app/agents/problem_analysis_agent.py`)
- Product Planning → Agent Runtime: extends (evidence: `backend/app/agents/product_agent.py`)
- System Design → Agent Runtime: extends (evidence: `backend/app/agents/system_design_agent.py`)
- Plan Validation → Agent Runtime: extends (evidence: `backend/app/agents/validation_engine.py`)
- Planning Pipeline → Project Records: updates (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Pages and Canvas: stores outputs (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Plan Graph Data: stores plan entities (evidence: `backend/app/graph/pipeline.py`)
- Planning Pipeline → Agent Run Records: tracks stages (evidence: `backend/app/graph/pipeline.py`)
- Project Records → SQL Database: persists in (evidence: `backend/app/models/project.py`)
- Pages and Canvas → SQL Database: persists in (evidence: `backend/app/models/page.py`)
- Plan Graph Data → SQL Database: persists in (evidence: `backend/app/models/graph_models.py`)
- Agent Run Records → SQL Database: persists in (evidence: `backend/app/models/agent_run.py`)