# abdelalikholty/terasprint architecture

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

- Interactive diagram: https://gitdiagram.com/abdelalikholty/terasprint
- Repository: https://github.com/abdelalikholty/terasprint

## Overview

TeraSprint is an AI-assisted agile planning and coding platform. Users submit an idea for project generation, manage the resulting backlog and sprints, then work with an AI coding agent in a live IDE workspace. The graph preserves the documented planning, Kanban, sandbox execution, provider resilience, persistence, and GitHub capabilities. Several backend and frontend modules were not sampled; their nodes reflect the tree and README, and links are limited to indexed references or documented relationships.

Main entry points: [`frontend/src/pages/workspace/CodingWorkspacePage.tsx`](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/CodingWorkspacePage.tsx) (IDE Workspace), [`frontend/src/App.tsx`](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/App.tsx) (Application Routes), [`backend/services/agents/coding/orchestrator.py`](https://github.com/abdelalikholty/terasprint/blob/main/backend/services/agents/coding/orchestrator.py) (Coding Orchestrator), [`frontend/src/services/api.ts`](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/services/api.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Planning &amp; Projects"]
  node_generator["Project Generator"]
  node_backlog["Agile Backlog<br/>[BacklogPage.tsx]"]
  node_sprints["Sprint Planning<br/>[SprintsPage.tsx]"]
end

subgraph group_workspace["Coding Workspace"]
  node_workspace_ui["IDE Workspace"]
  node_chat["Agent Chat"]
  node_files_ui["IDE File Tools"]
end

subgraph group_backend["Backend Services"]
  node_project_api["Project API<br/>[projects.py]"]
  node_coding_route["Coding API<br/>[coding.py]"]
  node_websockets["Live Events<br/>[websockets.py]"]
  node_agent["Coding Orchestrator<br/>[orchestrator.py]"]
  node_sandbox["Execution Sandbox<br/>[sandbox.py]"]
  node_llm["LLM Routing<br/>[llm_factory.py]"]
  node_auth_route["Authentication API<br/>[auth.py]"]
  node_files_route["Project Files API<br/>[files.py]"]
end

subgraph group_state["Persistence"]
  node_project_db[("Project Domain<br/>[project_db.py]")]
  node_db[("PostgreSQL<br/>[postgres.py]")]
  node_workspace_state[("Workspace Records")]
  node_storage[("File Storage<br/>[storage_service.py]")]
end

subgraph group_frontend["Frontend"]
  node_app["Application Routes<br/>[App.tsx]"]
  node_auth_ui["Authentication State<br/>[AuthContext.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
end

node_user(("Developer"))
node_observability["Arize Phoenix"]
node_github["GitHub"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_generator
node_generator -->|"requests"| node_api_client
node_api_client -.->|"calls API"| node_project_api
node_project_api -->|"reads/writes"| node_project_db
node_app -->|"routes to"| node_backlog
node_app -->|"routes to"| node_sprints
node_backlog -.->|"requests"| node_api_client
node_sprints -.->|"requests"| node_api_client
node_app -->|"routes to"| node_workspace_ui
node_workspace_ui -->|"renders"| node_chat
node_workspace_ui -->|"renders"| node_files_ui
node_workspace_ui -->|"requests"| node_api_client
node_workspace_ui -.->|"streams events"| node_websockets
node_coding_route -->|"invokes"| node_agent
node_websockets -->|"streams agent events"| node_agent
node_agent -->|"executes code"| node_sandbox
node_agent -->|"selects model"| node_llm
node_agent -.->|"traces calls"| node_observability
node_agent -.->|"publishes code"| node_github
node_auth_ui -->|"logs in"| node_auth_route
node_app -->|"provides state"| node_auth_ui
node_auth_route -->|"queries"| node_db
node_project_api -->|"uses sessions"| node_db
node_websockets -->|"persists workspace"| node_workspace_state
node_workspace_ui -.->|"loads workspace"| node_workspace_state
node_files_route -->|"uploads files"| node_storage
node_auth_route -->|"uploads avatars"| node_storage
node_storage -.->|"stores assets"| node_user
node_files_route -->|"records attachments"| node_project_db

click node_app "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/App.tsx"
click node_generator "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/ProjectGeneratorPage.tsx"
click node_project_api "https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/projects.py"
click node_backlog "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/dashboard/BacklogPage.tsx"
click node_sprints "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/dashboard/SprintsPage.tsx"
click node_project_db "https://github.com/abdelalikholty/terasprint/blob/main/backend/models/project_db.py"
click node_workspace_ui "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/CodingWorkspacePage.tsx"
click node_chat "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/components/TeraSprintChatWindow.tsx"
click node_files_ui "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/components/IDEFileExplorer.tsx"
click node_coding_route "https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/coding.py"
click node_websockets "https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/websockets.py"
click node_agent "https://github.com/abdelalikholty/terasprint/blob/main/backend/services/agents/coding/orchestrator.py"
click node_sandbox "https://github.com/abdelalikholty/terasprint/blob/main/backend/services/agents/coding/sandbox.py"
click node_llm "https://github.com/abdelalikholty/terasprint/blob/main/backend/services/llm_factory.py"
click node_auth_ui "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/context/AuthContext.tsx"
click node_auth_route "https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/auth.py"
click node_api_client "https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/services/api.ts"
click node_db "https://github.com/abdelalikholty/terasprint/blob/main/backend/db/postgres.py"
click node_workspace_state "https://github.com/abdelalikholty/terasprint/blob/main/backend/models/workspace_session.py"
click node_storage "https://github.com/abdelalikholty/terasprint/blob/main/backend/services/storage_service.py"
click node_files_route "https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/files.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_generator,node_backlog,node_sprints toneBlue
class node_workspace_ui,node_chat,node_files_ui toneAmber
class node_project_api,node_coding_route,node_websockets,node_agent,node_sandbox,node_llm,node_auth_route,node_files_route toneMint
class node_project_db,node_db,node_workspace_state,node_storage toneRose
class node_app,node_auth_ui,node_api_client,node_user,node_observability,node_github toneIndigo
```

## Components

### Planning & Projects

- [Project Generator](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/ProjectGeneratorPage.tsx): `frontend/src/pages/ProjectGeneratorPage.tsx`
- [Agile Backlog](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/dashboard/BacklogPage.tsx): `frontend/src/pages/dashboard/BacklogPage.tsx`
- [Sprint Planning](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/dashboard/SprintsPage.tsx): `frontend/src/pages/dashboard/SprintsPage.tsx`

### Coding Workspace

- [IDE Workspace](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/CodingWorkspacePage.tsx): `frontend/src/pages/workspace/CodingWorkspacePage.tsx`
- [Agent Chat](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/components/TeraSprintChatWindow.tsx): `frontend/src/pages/workspace/components/TeraSprintChatWindow.tsx`
- [IDE File Tools](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/pages/workspace/components/IDEFileExplorer.tsx): `frontend/src/pages/workspace/components/IDEFileExplorer.tsx`

### Backend Services

- [Project API](https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/projects.py): `backend/api/routes/projects.py`
- [Coding API](https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/coding.py): `backend/api/routes/coding.py`
- [Live Events](https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/websockets.py): `backend/api/routes/websockets.py`
- [Coding Orchestrator](https://github.com/abdelalikholty/terasprint/blob/main/backend/services/agents/coding/orchestrator.py): `backend/services/agents/coding/orchestrator.py`
- [Execution Sandbox](https://github.com/abdelalikholty/terasprint/blob/main/backend/services/agents/coding/sandbox.py): `backend/services/agents/coding/sandbox.py`
- [LLM Routing](https://github.com/abdelalikholty/terasprint/blob/main/backend/services/llm_factory.py): `backend/services/llm_factory.py`
- [Authentication API](https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/auth.py): `backend/api/routes/auth.py`
- [Project Files API](https://github.com/abdelalikholty/terasprint/blob/main/backend/api/routes/files.py): `backend/api/routes/files.py`

### Persistence

- [Project Domain](https://github.com/abdelalikholty/terasprint/blob/main/backend/models/project_db.py): `backend/models/project_db.py`
- [PostgreSQL](https://github.com/abdelalikholty/terasprint/blob/main/backend/db/postgres.py): `backend/db/postgres.py`
- [Workspace Records](https://github.com/abdelalikholty/terasprint/blob/main/backend/models/workspace_session.py): `backend/models/workspace_session.py`
- [File Storage](https://github.com/abdelalikholty/terasprint/blob/main/backend/services/storage_service.py): `backend/services/storage_service.py`

### Frontend

- [Application Routes](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Authentication State](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API Client](https://github.com/abdelalikholty/terasprint/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Other components

- **Developer**
- **Arize Phoenix**
- **GitHub**

## Connections

- Developer → Application Routes: uses (evidence: `README.md`)
- Application Routes → Project Generator: routes to (evidence: `frontend/src/App.tsx`)
- Project Generator → API Client: requests (evidence: `frontend/src/pages/ProjectGeneratorPage.tsx`)
- API Client → Project API: calls API
- Project API → Project Domain: reads/writes (evidence: `backend/api/routes/projects.py`)
- Application Routes → Agile Backlog: routes to (evidence: `frontend/src/App.tsx`)
- Application Routes → Sprint Planning: routes to (evidence: `frontend/src/App.tsx`)
- Agile Backlog → API Client: requests
- Sprint Planning → API Client: requests
- Application Routes → IDE Workspace: routes to (evidence: `frontend/src/App.tsx`)
- IDE Workspace → Agent Chat: renders (evidence: `frontend/src/pages/workspace/CodingWorkspacePage.tsx`)
- IDE Workspace → IDE File Tools: renders (evidence: `frontend/src/pages/workspace/CodingWorkspacePage.tsx`)
- IDE Workspace → API Client: requests (evidence: `frontend/src/pages/workspace/CodingWorkspacePage.tsx`)
- IDE Workspace → Live Events: streams events (evidence: `README.md`)
- Coding API → Coding Orchestrator: invokes (evidence: `backend/api/routes/coding.py`)
- Live Events → Coding Orchestrator: streams agent events (evidence: `backend/api/routes/websockets.py`)
- Coding Orchestrator → Execution Sandbox: executes code (evidence: `backend/services/agents/coding/orchestrator.py`)
- Coding Orchestrator → LLM Routing: selects model (evidence: `backend/services/agents/coding/orchestrator.py`)
- Coding Orchestrator → Arize Phoenix: traces calls (evidence: `README.md`)
- Coding Orchestrator → GitHub: publishes code (evidence: `README.md`)
- Authentication State → Authentication API: logs in (evidence: `frontend/src/context/AuthContext.tsx`)
- Application Routes → Authentication State: provides state (evidence: `frontend/src/App.tsx`)
- Authentication API → PostgreSQL: queries (evidence: `backend/api/routes/auth.py`)
- Project API → PostgreSQL: uses sessions (evidence: `backend/api/routes/projects.py`)
- Live Events → Workspace Records: persists workspace (evidence: `backend/api/routes/websockets.py`)
- IDE Workspace → Workspace Records: loads workspace
- Project Files API → File Storage: uploads files (evidence: `backend/api/routes/files.py`)
- Authentication API → File Storage: uploads avatars (evidence: `backend/api/routes/auth.py`)
- File Storage → Developer: stores assets
- Project Files API → Project Domain: records attachments (evidence: `backend/api/routes/files.py`)
