# satvik219/reqsphere-ai architecture

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

- Interactive diagram: https://gitdiagram.com/satvik219/reqsphere-ai
- Repository: https://github.com/satvik219/reqsphere-ai

## Overview

ReqSphere AI turns business evidence into traceable requirements and BRDs. Users sign in, work in a project workspace, review evidence and extracted requirements, resolve conflicts and gaps, and generate a traceable BRD. The frontend data boundary supports mock data or the Express API; backend extraction can call Gemini. The README also documents risks, dependencies, and change views. Edges reflect the supplied excerpts and README; unsampled UI and route wiring is not inferred.

Main entry points: [`backend/src/app.js`](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/app.js) (Express API app), [`backend/src/routes/authRoutes.js`](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/routes/authRoutes.js) (Authentication routes), [`backend/src/routes/apiRoutes.js`](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/routes/apiRoutes.js) (Workspace API routes), [`frontend/src/auth/authService.js`](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/auth/authService.js) (Session and auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend experience"]
  node_authui["Sign-in screens<br/>[LoginPage.jsx]"]
  node_signupui["Registration screen<br/>[SignupPage.jsx]"]
  node_workspaceui["Workspace views<br/>[main.jsx]"]
  node_frontendservices["Workspace data services<br/>[data.js]"]
  node_mockdata["Mock domain data"]
  node_authservice["Session and auth<br/>[authService.js]"]
  node_apiclient["HTTP client<br/>[client.js]"]
end

subgraph group_api["API and identity"]
  node_backendapp["Express API app<br/>[app.js]"]
  node_authroutes["Authentication routes<br/>[authRoutes.js]"]
  node_authmiddleware["JWT middleware<br/>[auth.js]"]
  node_userrepo[("User repository<br/>[userRepository.js]")]
  node_apiroutes["Workspace API routes<br/>[apiRoutes.js]"]
  node_config["Runtime configuration<br/>[config.js]"]
end

subgraph group_domain["Requirements intelligence"]
  node_domainrepo[("Workspace repository<br/>[localRepository.js]")]
  node_workspaceservice["Workspace analysis and BRD"]
  node_requirementagent["Requirement extraction"]
  node_requirementschema["Requirement validation schema"]
end

subgraph group_integrations["External services"]
  node_gemini["Gemini client<br/>[geminiClient.js]"]
  node_firebase["Firebase authentication"]
  node_vertex["Vertex AI / Gemini"]
end

node_analyst(("Business analyst"))

node_analyst -->|"signs in"| node_authui
node_analyst -->|"registers"| node_signupui
node_analyst -->|"uses workspace"| node_workspaceui
node_workspaceui -->|"loads domain data"| node_frontendservices
node_frontendservices -->|"reads in mock mode"| node_mockdata
node_frontendservices -->|"requests in API mode"| node_apiclient
node_authui -->|"invokes auth"| node_authservice
node_signupui -->|"invokes registration"| node_authservice
node_authservice -->|"sends auth requests"| node_apiclient
node_authservice -->|"obtains Google token"| node_firebase
node_apiclient -.->|"calls API"| node_backendapp
node_backendapp -->|"mounts auth routes"| node_authroutes
node_backendapp -->|"protects API routes"| node_authmiddleware
node_backendapp -->|"mounts protected routes"| node_apiroutes
node_authroutes -->|"authenticates and registers"| node_userrepo
node_authroutes -->|"signs JWTs"| node_config
node_authmiddleware -->|"reads JWT settings"| node_config
node_apiroutes -->|"reads and updates records"| node_domainrepo
node_apiroutes -->|"requests summaries and BRD"| node_workspaceservice
node_workspaceservice -->|"aggregates and reads data"| node_domainrepo
node_apiroutes -->|"extracts requirements"| node_requirementagent
node_requirementagent -->|"validates output"| node_requirementschema
node_requirementagent -->|"requests generation"| node_gemini
node_gemini -->|"loads model settings"| node_config
node_gemini -->|"generates text"| node_vertex
node_authroutes -.->|"verifies ID token"| node_firebase

click node_authui "https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/components/auth/LoginPage.jsx"
click node_signupui "https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/components/auth/SignupPage.jsx"
click node_workspaceui "https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/main.jsx"
click node_frontendservices "https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/services/data.js"
click node_mockdata "https://github.com/satvik219/reqsphere-ai/tree/main/frontend/src/mocks"
click node_authservice "https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/auth/authService.js"
click node_apiclient "https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/api/client.js"
click node_backendapp "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/app.js"
click node_authroutes "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/routes/authRoutes.js"
click node_authmiddleware "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/middleware/auth.js"
click node_userrepo "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/repositories/userRepository.js"
click node_apiroutes "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/routes/apiRoutes.js"
click node_config "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/config.js"
click node_domainrepo "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/repositories/localRepository.js"
click node_workspaceservice "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/services/workspaceService.js"
click node_requirementagent "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/services/ai/requirementAgent.js"
click node_requirementschema "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/schemas/requirementSchema.js"
click node_gemini "https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/services/ai/geminiClient.js"

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_authui,node_signupui,node_workspaceui,node_frontendservices,node_mockdata,node_authservice,node_apiclient toneBlue
class node_backendapp,node_authroutes,node_authmiddleware,node_userrepo,node_apiroutes,node_config toneAmber
class node_domainrepo,node_workspaceservice,node_requirementagent,node_requirementschema toneMint
class node_gemini,node_firebase,node_vertex toneRose
class node_analyst toneIndigo
```

## Components

### Frontend experience

- [Sign-in screens](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/components/auth/LoginPage.jsx): `frontend/src/components/auth/LoginPage.jsx`
- [Registration screen](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/components/auth/SignupPage.jsx): `frontend/src/components/auth/SignupPage.jsx`
- [Workspace views](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Workspace data services](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/services/data.js): `frontend/src/services/data.js`
- [Mock domain data](https://github.com/satvik219/reqsphere-ai/tree/main/frontend/src/mocks): `frontend/src/mocks`
- [Session and auth](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/auth/authService.js): `frontend/src/auth/authService.js`
- [HTTP client](https://github.com/satvik219/reqsphere-ai/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API and identity

- [Express API app](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/app.js): `backend/src/app.js`
- [Authentication routes](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/routes/authRoutes.js): `backend/src/routes/authRoutes.js`
- [JWT middleware](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [User repository](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/repositories/userRepository.js): `backend/src/repositories/userRepository.js`
- [Workspace API routes](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/routes/apiRoutes.js): `backend/src/routes/apiRoutes.js`
- [Runtime configuration](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/config.js): `backend/src/config.js`

### Requirements intelligence

- [Workspace repository](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/repositories/localRepository.js): `backend/src/repositories/localRepository.js`
- [Workspace analysis and BRD](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/services/workspaceService.js): `backend/src/services/workspaceService.js`
- [Requirement extraction](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/services/ai/requirementAgent.js): `backend/src/services/ai/requirementAgent.js`
- [Requirement validation schema](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/schemas/requirementSchema.js): `backend/src/schemas/requirementSchema.js`

### External services

- [Gemini client](https://github.com/satvik219/reqsphere-ai/blob/main/backend/src/services/ai/geminiClient.js): `backend/src/services/ai/geminiClient.js`
- **Firebase authentication**
- **Vertex AI / Gemini**

### Other components

- **Business analyst**

## Connections

- Business analyst → Sign-in screens: signs in
- Business analyst → Registration screen: registers
- Business analyst → Workspace views: uses workspace (evidence: `frontend/src/main.jsx`)
- Workspace views → Workspace data services: loads domain data (evidence: `frontend/src/main.jsx`)
- Workspace data services → Mock domain data: reads in mock mode (evidence: `frontend/src/services/data.js`)
- Workspace data services → HTTP client: requests in API mode (evidence: `frontend/src/services/data.js`)
- Sign-in screens → Session and auth: invokes auth (evidence: `frontend/src/components/auth/LoginPage.jsx`)
- Registration screen → Session and auth: invokes registration (evidence: `frontend/src/components/auth/SignupPage.jsx`)
- Session and auth → HTTP client: sends auth requests (evidence: `frontend/src/auth/authService.js`)
- Session and auth → Firebase authentication: obtains Google token (evidence: `frontend/src/auth/authService.js`)
- HTTP client → Express API app: calls API
- Express API app → Authentication routes: mounts auth routes (evidence: `backend/src/app.js`)
- Express API app → JWT middleware: protects API routes (evidence: `backend/src/app.js`)
- Express API app → Workspace API routes: mounts protected routes (evidence: `backend/src/app.js`)
- Authentication routes → User repository: authenticates and registers (evidence: `backend/src/routes/authRoutes.js`)
- Authentication routes → Runtime configuration: signs JWTs (evidence: `backend/src/routes/authRoutes.js`)
- JWT middleware → Runtime configuration: reads JWT settings (evidence: `backend/src/middleware/auth.js`)
- Workspace API routes → Workspace repository: reads and updates records (evidence: `backend/src/routes/apiRoutes.js`)
- Workspace API routes → Workspace analysis and BRD: requests summaries and BRD (evidence: `backend/src/routes/apiRoutes.js`)
- Workspace analysis and BRD → Workspace repository: aggregates and reads data (evidence: `backend/src/services/workspaceService.js`)
- Workspace API routes → Requirement extraction: extracts requirements (evidence: `backend/src/routes/apiRoutes.js`)
- Requirement extraction → Requirement validation schema: validates output (evidence: `backend/src/services/ai/requirementAgent.js`)
- Requirement extraction → Gemini client: requests generation (evidence: `backend/src/services/ai/requirementAgent.js`)
- Gemini client → Runtime configuration: loads model settings (evidence: `backend/src/services/ai/geminiClient.js`)
- Gemini client → Vertex AI / Gemini: generates text (evidence: `backend/src/services/ai/geminiClient.js`)
- Authentication routes → Firebase authentication: verifies ID token
