# nishantdasari-hub/speakforge architecture

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

- Interactive diagram: https://gitdiagram.com/nishantdasari-hub/speakforge
- Repository: https://github.com/nishantdasari-hub/speakforge

## Overview

SpeakForge is a learner assessment and administration platform. Learners register and verify accounts, take text or audio tests, then review scored answers, reports, and progress; administrators manage tests/questions and inspect analytics. The frontend routes users to these experiences and calls a FastAPI backend, which handles authentication, assessment, and persistence. The README documents the evaluation stages, but the test routes and scoring implementation were not excerpted, so their internal call sequence is not asserted here.

Main entry points: [`frontend/src/App.jsx`](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/App.jsx) (Route application), [`backend/app/services/ai_scoring.py`](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py) (AI scoring), [`backend/app/main.py`](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/api.js`](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Route application<br/>[App.jsx]"]
  node_auth_pages["Account pages<br/>[Login.jsx]"]
  node_test_pages["Test-taking pages<br/>[TestDetail.jsx]"]
  node_report_pages["Reports and progress<br/>[TestReport.jsx]"]
  node_admin_pages["Admin pages<br/>[AdminQuestions.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["Backend workflows"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_test_routes["Test routes<br/>[test.py]"]
  node_report_routes["Report routes<br/>[report.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_test_service["Test service<br/>[test_service.py]"]
end

subgraph group_evaluation["Assessment evaluation"]
  node_ai_scoring["AI scoring<br/>[ai_scoring.py]"]
  node_transcription["Audio transcription<br/>[ai_scoring.py]"]
  node_grammar["Grammar analysis<br/>[ai_scoring.py]"]
end

subgraph group_state["Persistence and services"]
  node_database["Database session<br/>[database.py]"]
  node_models["Assessment records<br/>[models.py]"]
  node_mail["Email delivery<br/>[email.py]"]
end

node_learner(("Learner"))
node_admin(("Administrator"))
node_mailer["Email service"]

node_learner -->|"uses"| node_app
node_admin -->|"uses"| node_app
node_app -->|"routes to"| node_auth_pages
node_app -->|"routes to"| node_test_pages
node_app -->|"routes to"| node_report_pages
node_app -->|"routes to"| node_admin_pages
node_auth_pages -.->|"authenticates via"| node_api_client
node_test_pages -.->|"requests tests"| node_api_client
node_report_pages -->|"loads results"| node_api_client
node_admin_pages -->|"manages questions"| node_api_app
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_test_routes
node_api_app -->|"mounts"| node_report_routes
node_auth_routes -->|"delegates to"| node_auth_service
node_auth_routes -->|"sends messages"| node_mail
node_mail -->|"delivers through"| node_mailer
node_auth_service -->|"opens sessions"| node_database
node_auth_service -->|"queries users"| node_models
node_test_routes -.->|"delegates to"| node_test_service
node_test_service -.->|"evaluates responses"| node_ai_scoring
node_ai_scoring -->|"transcribes audio"| node_transcription
node_transcription -->|"passes transcript"| node_grammar
node_ai_scoring -->|"analyzes text"| node_grammar
node_ai_scoring -.->|"uses persistence"| node_database
node_ai_scoring -.->|"records evaluations"| node_models
node_report_routes -->|"loads reports"| node_database
node_report_routes -->|"reads results"| node_models
node_database -->|"maps records"| node_models

click node_app "https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/App.jsx"
click node_auth_pages "https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/Login.jsx"
click node_test_pages "https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/TestDetail.jsx"
click node_report_pages "https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/TestReport.jsx"
click node_admin_pages "https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/AdminQuestions.jsx"
click node_api_client "https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/api.js"
click node_api_app "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/routes/auth.py"
click node_test_routes "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/routes/test.py"
click node_report_routes "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/routes/report.py"
click node_auth_service "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/auth_service.py"
click node_test_service "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/test_service.py"
click node_ai_scoring "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py"
click node_transcription "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py"
click node_grammar "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py"
click node_database "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/database.py"
click node_models "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/models.py"
click node_mail "https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/utils/email.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_app,node_auth_pages,node_test_pages,node_report_pages,node_admin_pages,node_api_client toneBlue
class node_api_app,node_auth_routes,node_test_routes,node_report_routes,node_auth_service,node_test_service toneAmber
class node_ai_scoring,node_transcription,node_grammar toneMint
class node_database,node_models,node_mail toneRose
class node_learner,node_admin,node_mailer toneIndigo
```

## Components

### Web application

- [Route application](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Account pages](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Test-taking pages](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/TestDetail.jsx): `frontend/src/pages/TestDetail.jsx`
- [Reports and progress](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/TestReport.jsx): `frontend/src/pages/TestReport.jsx`
- [Admin pages](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/pages/AdminQuestions.jsx): `frontend/src/pages/AdminQuestions.jsx`
- [API client](https://github.com/nishantdasari-hub/speakforge/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Backend workflows

- [FastAPI application](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [Test routes](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/routes/test.py): `backend/app/routes/test.py`
- [Report routes](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/routes/report.py): `backend/app/routes/report.py`
- [Auth service](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Test service](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/test_service.py): `backend/app/services/test_service.py`

### Assessment evaluation

- [AI scoring](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py): `backend/app/services/ai_scoring.py`
- [Audio transcription](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py): `backend/app/services/ai_scoring.py`
- [Grammar analysis](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/services/ai_scoring.py): `backend/app/services/ai_scoring.py`

### Persistence and services

- [Database session](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/database.py): `backend/app/database.py`
- [Assessment records](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/models.py): `backend/app/models.py`
- [Email delivery](https://github.com/nishantdasari-hub/speakforge/blob/main/backend/app/utils/email.py): `backend/app/utils/email.py`

### Other components

- **Learner**
- **Administrator**
- **Email service**

## Connections

- Learner → Route application: uses (evidence: `frontend/src/App.jsx`)
- Administrator → Route application: uses (evidence: `frontend/src/App.jsx`)
- Route application → Account pages: routes to (evidence: `frontend/src/App.jsx`)
- Route application → Test-taking pages: routes to (evidence: `frontend/src/App.jsx`)
- Route application → Reports and progress: routes to (evidence: `frontend/src/App.jsx`)
- Route application → Admin pages: routes to (evidence: `frontend/src/App.jsx`)
- Account pages → API client: authenticates via
- Test-taking pages → API client: requests tests
- Reports and progress → API client: loads results (evidence: `frontend/src/api.js`)
- Admin pages → FastAPI application: manages questions (evidence: `frontend/src/pages/AdminQuestions.jsx`)
- API client → FastAPI application: calls API (evidence: `frontend/src/api.js`)
- FastAPI application → Authentication routes: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Test routes: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Report routes: mounts (evidence: `backend/app/main.py`)
- Authentication routes → Auth service: delegates to (evidence: `backend/app/routes/auth.py`)
- Authentication routes → Email delivery: sends messages (evidence: `backend/app/routes/auth.py`)
- Email delivery → Email service: delivers through (evidence: `backend/app/utils/email.py`)
- Auth service → Database session: opens sessions (evidence: `backend/app/services/auth_service.py`)
- Auth service → Assessment records: queries users (evidence: `backend/app/services/auth_service.py`)
- Test routes → Test service: delegates to
- Test service → AI scoring: evaluates responses
- AI scoring → Audio transcription: transcribes audio (evidence: `README.md`)
- Audio transcription → Grammar analysis: passes transcript (evidence: `README.md`)
- AI scoring → Grammar analysis: analyzes text (evidence: `README.md`)
- AI scoring → Database session: uses persistence (evidence: `backend/app/services/ai_scoring.py`)
- AI scoring → Assessment records: records evaluations (evidence: `backend/app/services/ai_scoring.py`)
- Report routes → Database session: loads reports (evidence: `backend/app/routes/report.py`)
- Report routes → Assessment records: reads results (evidence: `backend/app/routes/report.py`)
- Database session → Assessment records: maps records (evidence: `backend/app/models.py`)
