# cpk2006/specmind-ai architecture

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

- Interactive diagram: https://gitdiagram.com/cpk2006/specmind-ai
- Repository: https://github.com/cpk2006/specmind-ai

## Overview

SpecMind AI turns either an idea or an uploaded specification into a persistent requirements workspace with tests, quality findings, diagrams, and exportable SRS content. Users enter through the React workspace and FastAPI routes; project and requirement workflows invoke the relevant services, which coordinate AI generation, document handling, and persistence. The README documents provider failover and broader workspace features, but some implementation files and frontend API calls were not excerpted, so those relationships are shown only where documentation or the source index supports them.

Main entry points: [`backend/app/services/requirement_service.py`](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/services/requirement_service.py) (Requirement workflow), [`backend/app/api/v1/routers/project.py`](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/project.py) (Project routes), [`backend/app/core/auth_dependencies.py`](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/core/auth_dependencies.py) (JWT authorization), [`backend/app/main.py`](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web workspace"]
  node_web["Workspace UI<br/>[main.jsx]"]
  node_diagram_view["Diagram preview<br/>[DiagramPreview.jsx]"]
  node_diagram_utils["Diagram utilities<br/>[diagramUtils.js]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_project_routes["Project routes<br/>[project.py]"]
  node_requirement_routes["Requirement routes<br/>[requirement.py]"]
  node_auth_guard["JWT authorization"]
  node_security["Token security<br/>[security.py]"]
end

subgraph group_workflow["Requirements workflows"]
  node_project_service["Project workflow<br/>[project_service.py]"]
  node_requirement_service["Requirement workflow"]
end

subgraph group_intelligence["AI and documents"]
  node_ai["AI generation and review<br/>[gemini_service.py]"]
  node_prompts["Prompt resources<br/>[prompts.py]"]
  node_parser["Document parsing<br/>[document_parser.py]"]
  node_uploads["Upload storage<br/>[file_storage.py]"]
end

subgraph group_persistence["Persistence"]
  node_project_repo["Project repository"]
  node_requirement_repo["Requirement repository"]
  node_models["Domain records<br/>[project.py]"]
  node_requirement_model["Requirement record<br/>[requirement.py]"]
  node_user_model["User record<br/>[user.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
end

node_user(("Team member"))
node_postgres[("PostgreSQL")]
node_ai_providers{{"AI providers"}}

node_user -->|"uses"| node_web
node_web -->|"renders diagrams"| node_diagram_view
node_diagram_view -->|"uses"| node_diagram_utils
node_web -.->|"calls API"| node_app
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_project_routes
node_app -->|"registers"| node_requirement_routes
node_auth_routes -->|"uses"| node_security
node_project_routes -->|"authorizes"| node_auth_guard
node_requirement_routes -->|"authorizes"| node_auth_guard
node_auth_guard -->|"decodes token"| node_security
node_auth_guard -->|"loads user"| node_user_model
node_project_routes -->|"delegates"| node_project_service
node_project_routes -->|"requests report"| node_requirement_service
node_requirement_routes -->|"delegates"| node_requirement_service
node_project_service -->|"delegates"| node_project_repo
node_requirement_service -->|"reads and saves"| node_requirement_repo
node_requirement_service -->|"loads project"| node_project_repo
node_requirement_service -->|"generates and reviews"| node_ai
node_requirement_service -->|"extracts text"| node_parser
node_requirement_service -->|"saves uploads"| node_uploads
node_project_routes -->|"generates and repairs diagrams"| node_ai
node_ai -->|"uses prompts"| node_prompts
node_ai -.->|"routes with failover"| node_ai_providers
node_project_repo -->|"persists projects"| node_models
node_requirement_repo -->|"persists requirements"| node_requirement_model
node_auth_guard -->|"gets session"| node_db_session
node_db_session -.->|"connects"| node_postgres

click node_web "https://github.com/cpk2006/specmind-ai/blob/main/frontend/src/main.jsx"
click node_diagram_view "https://github.com/cpk2006/specmind-ai/blob/main/frontend/src/components/DiagramPreview.jsx"
click node_diagram_utils "https://github.com/cpk2006/specmind-ai/blob/main/frontend/src/diagramUtils.js"
click node_app "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/auth.py"
click node_project_routes "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/project.py"
click node_requirement_routes "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/requirement.py"
click node_auth_guard "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/core/auth_dependencies.py"
click node_security "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/core/security.py"
click node_project_service "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/services/project_service.py"
click node_requirement_service "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/services/requirement_service.py"
click node_ai "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/ai/gemini_service.py"
click node_prompts "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/ai/prompts.py"
click node_parser "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/utils/document_parser.py"
click node_uploads "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/utils/file_storage.py"
click node_project_repo "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/repositories/project_repository.py"
click node_requirement_repo "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/repositories/requirement_repository.py"
click node_models "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/models/project.py"
click node_requirement_model "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/models/requirement.py"
click node_user_model "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/models/user.py"
click node_db_session "https://github.com/cpk2006/specmind-ai/blob/main/backend/app/database/session.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,node_diagram_view,node_diagram_utils toneBlue
class node_app,node_auth_routes,node_project_routes,node_requirement_routes,node_auth_guard,node_security,node_postgres toneAmber
class node_project_service,node_requirement_service toneMint
class node_ai,node_prompts,node_parser,node_uploads toneRose
class node_project_repo,node_requirement_repo,node_models,node_requirement_model,node_user_model,node_db_session,node_user,node_ai_providers toneIndigo
```

## Components

### Web workspace

- [Workspace UI](https://github.com/cpk2006/specmind-ai/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Diagram preview](https://github.com/cpk2006/specmind-ai/blob/main/frontend/src/components/DiagramPreview.jsx): `frontend/src/components/DiagramPreview.jsx`
- [Diagram utilities](https://github.com/cpk2006/specmind-ai/blob/main/frontend/src/diagramUtils.js): `frontend/src/diagramUtils.js`

### API and identity

- [FastAPI app](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/auth.py): `backend/app/api/v1/routers/auth.py`
- [Project routes](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/project.py): `backend/app/api/v1/routers/project.py`
- [Requirement routes](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/api/v1/routers/requirement.py): `backend/app/api/v1/routers/requirement.py`
- [JWT authorization](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/core/auth_dependencies.py): `backend/app/core/auth_dependencies.py`
- [Token security](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Requirements workflows

- [Project workflow](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/services/project_service.py): `backend/app/services/project_service.py`
- [Requirement workflow](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/services/requirement_service.py): `backend/app/services/requirement_service.py`

### AI and documents

- [AI generation and review](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/ai/gemini_service.py): `backend/app/ai/gemini_service.py`
- [Prompt resources](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/ai/prompts.py): `backend/app/ai/prompts.py`
- [Document parsing](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/utils/document_parser.py): `backend/app/utils/document_parser.py`
- [Upload storage](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/utils/file_storage.py): `backend/app/utils/file_storage.py`

### Persistence

- [Project repository](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/repositories/project_repository.py): `backend/app/repositories/project_repository.py`
- [Requirement repository](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/repositories/requirement_repository.py): `backend/app/repositories/requirement_repository.py`
- [Domain records](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [Requirement record](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/models/requirement.py): `backend/app/models/requirement.py`
- [User record](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Database sessions](https://github.com/cpk2006/specmind-ai/blob/main/backend/app/database/session.py): `backend/app/database/session.py`

### Other components

- **Team member**
- **PostgreSQL**
- **AI providers**

## Connections

- Team member → Workspace UI: uses
- Workspace UI → Diagram preview: renders diagrams (evidence: `frontend/src/main.jsx`)
- Diagram preview → Diagram utilities: uses (evidence: `frontend/src/components/DiagramPreview.jsx`)
- Workspace UI → FastAPI app: calls API
- FastAPI app → Auth routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Project routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Requirement routes: registers (evidence: `backend/app/main.py`)
- Auth routes → Token security: uses (evidence: `backend/app/api/v1/routers/auth.py`)
- Project routes → JWT authorization: authorizes (evidence: `backend/app/api/v1/routers/project.py`)
- Requirement routes → JWT authorization: authorizes (evidence: `backend/app/api/v1/routers/requirement.py`)
- JWT authorization → Token security: decodes token (evidence: `backend/app/core/auth_dependencies.py`)
- JWT authorization → User record: loads user (evidence: `backend/app/core/auth_dependencies.py`)
- Project routes → Project workflow: delegates (evidence: `backend/app/api/v1/routers/project.py`)
- Project routes → Requirement workflow: requests report (evidence: `backend/app/api/v1/routers/project.py`)
- Requirement routes → Requirement workflow: delegates (evidence: `backend/app/api/v1/routers/requirement.py`)
- Project workflow → Project repository: delegates (evidence: `backend/app/services/project_service.py`)
- Requirement workflow → Requirement repository: reads and saves (evidence: `backend/app/services/requirement_service.py`)
- Requirement workflow → Project repository: loads project (evidence: `backend/app/services/requirement_service.py`)
- Requirement workflow → AI generation and review: generates and reviews (evidence: `backend/app/services/requirement_service.py`)
- Requirement workflow → Document parsing: extracts text (evidence: `backend/app/services/requirement_service.py`)
- Requirement workflow → Upload storage: saves uploads (evidence: `backend/app/services/requirement_service.py`)
- Project routes → AI generation and review: generates and repairs diagrams (evidence: `backend/app/api/v1/routers/project.py`)
- AI generation and review → Prompt resources: uses prompts (evidence: `backend/app/ai/gemini_service.py`)
- AI generation and review → AI providers: routes with failover
- Project repository → Domain records: persists projects (evidence: `backend/app/repositories/project_repository.py`)
- Requirement repository → Requirement record: persists requirements (evidence: `backend/app/repositories/requirement_repository.py`)
- JWT authorization → Database sessions: gets session (evidence: `backend/app/core/auth_dependencies.py`)
- Database sessions → PostgreSQL: connects
