# suryakumar2408/brainhire architecture

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

- Interactive diagram: https://gitdiagram.com/suryakumar2408/brainhire
- Repository: https://github.com/suryakumar2408/brainhire

## Overview

BrainHire is an interview-preparation web application. Users register or sign in, provide a resume or self-description and a job description, then review generated interview reports and can download a resume PDF. The frontend also supports report history and report detail views. The graph captures the documented routing and sampled controller relationships; frontend API-to-backend transport and the AI service’s external provider are not shown in the excerpts, so those links are omitted.

Main entry points: [`frontend/src/app.routes.jsx`](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/app.routes.jsx) (App routes), [`backend/src/controllers/interview.controller.js`](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/controllers/interview.controller.js) (Report operations), [`frontend/src/features/auth/hooks/useAuth.js`](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/hooks/useAuth.js) (Auth actions), [`backend/src/routes/auth.routes.js`](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/routes/auth.routes.js) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_landing["Landing page<br/>[Landing.jsx]"]
  node_app_router["App routes<br/>[app.routes.jsx]"]
end

subgraph group_identity["Identity"]
  node_auth_pages["Login and register<br/>[Login.jsx]"]
  node_auth_state["Auth state<br/>[auth.context.jsx]"]
  node_auth_hook["Auth actions<br/>[useAuth.js]"]
  node_auth_api["Auth API client<br/>[auth.api.js]"]
  node_protected["Route protection<br/>[Protected.jsx]"]
end

subgraph group_interview["Interview preparation"]
  node_dashboard["Report dashboard<br/>[Home.jsx]"]
  node_interview_view["Report detail<br/>[Interview.jsx]"]
  node_interview_hook["Report actions<br/>[useInterview.js]"]
  node_interview_api["Interview API client<br/>[interview.api.js]"]
end

subgraph group_backend["Backend runtime"]
  node_backend_app["API application<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_interview_routes["Interview routes"]
  node_auth_controller["Auth operations<br/>[auth.controller.js]"]
  node_auth_middleware["Token validation<br/>[auth.middleware.js]"]
  node_interview_controller["Report operations"]
  node_ai_service["AI generation<br/>[ai.service.js]"]
end

subgraph group_data["Persistent data"]
  node_users[("User records<br/>[user.model.js]")]
  node_blacklist[("Token blacklist<br/>[blacklist.model.js]")]
  node_reports[("Interview reports")]
end

node_user(("User"))

node_user -->|"opens"| node_landing
node_user -->|"authenticates"| node_auth_pages
node_user -->|"reviews reports"| node_dashboard
node_user -->|"views report"| node_interview_view
node_app_router -->|"routes to"| node_landing
node_app_router -->|"routes to"| node_auth_pages
node_app_router -->|"guards routes"| node_protected
node_app_router -->|"routes to"| node_dashboard
node_app_router -->|"routes to"| node_interview_view
node_auth_pages -->|"uses"| node_auth_hook
node_auth_hook -->|"updates"| node_auth_state
node_auth_hook -->|"calls"| node_auth_api
node_auth_state -->|"checks session"| node_auth_api
node_protected -->|"checks identity"| node_auth_hook
node_dashboard -->|"uses"| node_interview_hook
node_interview_view -->|"uses"| node_interview_hook
node_interview_hook -->|"calls"| node_interview_api
node_backend_app -->|"mounts"| node_auth_routes
node_backend_app -->|"mounts"| node_interview_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_routes -->|"guards session"| node_auth_middleware
node_interview_routes -->|"guards requests"| node_auth_middleware
node_interview_routes -->|"dispatches"| node_interview_controller
node_auth_controller -->|"reads and writes"| node_users
node_auth_controller -->|"records logout token"| node_blacklist
node_auth_middleware -->|"checks token"| node_blacklist
node_interview_controller -->|"generates report"| node_ai_service
node_interview_controller -->|"stores and reads"| node_reports
node_interview_controller -->|"generates resume PDF"| node_ai_service

click node_landing "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/landing/pages/Landing.jsx"
click node_app_router "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/app.routes.jsx"
click node_auth_pages "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/pages/Login.jsx"
click node_auth_state "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/auth.context.jsx"
click node_auth_hook "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/hooks/useAuth.js"
click node_auth_api "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/services/auth.api.js"
click node_protected "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/components/Protected.jsx"
click node_dashboard "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/pages/Home.jsx"
click node_interview_view "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/pages/Interview.jsx"
click node_interview_hook "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/hooks/useInterview.js"
click node_interview_api "https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/services/interview.api.js"
click node_backend_app "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/app.js"
click node_auth_routes "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/routes/auth.routes.js"
click node_interview_routes "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/routes/interview.routes.js"
click node_auth_controller "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/controllers/auth.controller.js"
click node_auth_middleware "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/middlewares/auth.middleware.js"
click node_interview_controller "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/controllers/interview.controller.js"
click node_ai_service "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/services/ai.service.js"
click node_users "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/models/user.model.js"
click node_blacklist "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/models/blacklist.model.js"
click node_reports "https://github.com/suryakumar2408/brainhire/blob/main/backend/src/models/interviewReport.model.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_landing,node_app_router,node_user toneBlue
class node_auth_pages,node_auth_state,node_auth_hook,node_auth_api,node_protected toneAmber
class node_dashboard,node_interview_view,node_interview_hook,node_interview_api toneMint
class node_backend_app,node_auth_routes,node_interview_routes,node_auth_controller,node_auth_middleware,node_interview_controller,node_ai_service toneRose
class node_users,node_blacklist,node_reports toneIndigo
```

## Components

### Web experience

- [Landing page](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/landing/pages/Landing.jsx): `frontend/src/features/landing/pages/Landing.jsx`
- [App routes](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/app.routes.jsx): `frontend/src/app.routes.jsx`

### Identity

- [Login and register](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/pages/Login.jsx): `frontend/src/features/auth/pages/Login.jsx`
- [Auth state](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/auth.context.jsx): `frontend/src/features/auth/auth.context.jsx`
- [Auth actions](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/hooks/useAuth.js): `frontend/src/features/auth/hooks/useAuth.js`
- [Auth API client](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/services/auth.api.js): `frontend/src/features/auth/services/auth.api.js`
- [Route protection](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/auth/components/Protected.jsx): `frontend/src/features/auth/components/Protected.jsx`

### Interview preparation

- [Report dashboard](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/pages/Home.jsx): `frontend/src/features/interview/pages/Home.jsx`
- [Report detail](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/pages/Interview.jsx): `frontend/src/features/interview/pages/Interview.jsx`
- [Report actions](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/hooks/useInterview.js): `frontend/src/features/interview/hooks/useInterview.js`
- [Interview API client](https://github.com/suryakumar2408/brainhire/blob/main/frontend/src/features/interview/services/interview.api.js): `frontend/src/features/interview/services/interview.api.js`

### Backend runtime

- [API application](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/app.js): `backend/src/app.js`
- [Auth routes](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [Interview routes](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/routes/interview.routes.js): `backend/src/routes/interview.routes.js`
- [Auth operations](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/controllers/auth.controller.js): `backend/src/controllers/auth.controller.js`
- [Token validation](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/middlewares/auth.middleware.js): `backend/src/middlewares/auth.middleware.js`
- [Report operations](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/controllers/interview.controller.js): `backend/src/controllers/interview.controller.js`
- [AI generation](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/services/ai.service.js): `backend/src/services/ai.service.js`

### Persistent data

- [User records](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/models/user.model.js): `backend/src/models/user.model.js`
- [Token blacklist](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/models/blacklist.model.js): `backend/src/models/blacklist.model.js`
- [Interview reports](https://github.com/suryakumar2408/brainhire/blob/main/backend/src/models/interviewReport.model.js): `backend/src/models/interviewReport.model.js`

### Other components

- **User**

## Connections

- User → Landing page: opens
- User → Login and register: authenticates
- User → Report dashboard: reviews reports
- User → Report detail: views report
- App routes → Landing page: routes to (evidence: `frontend/src/app.routes.jsx`)
- App routes → Login and register: routes to (evidence: `frontend/src/app.routes.jsx`)
- App routes → Route protection: guards routes (evidence: `frontend/src/app.routes.jsx`)
- App routes → Report dashboard: routes to (evidence: `frontend/src/app.routes.jsx`)
- App routes → Report detail: routes to (evidence: `frontend/src/app.routes.jsx`)
- Login and register → Auth actions: uses (evidence: `frontend/src/features/auth/hooks/useAuth.js`)
- Auth actions → Auth state: updates (evidence: `frontend/src/features/auth/hooks/useAuth.js`)
- Auth actions → Auth API client: calls (evidence: `frontend/src/features/auth/hooks/useAuth.js`)
- Auth state → Auth API client: checks session (evidence: `frontend/src/features/auth/auth.context.jsx`)
- Route protection → Auth actions: checks identity (evidence: `frontend/src/features/auth/components/Protected.jsx`)
- Report dashboard → Report actions: uses (evidence: `frontend/src/features/interview/hooks/useInterview.js`)
- Report detail → Report actions: uses (evidence: `frontend/src/features/interview/hooks/useInterview.js`)
- Report actions → Interview API client: calls (evidence: `frontend/src/features/interview/hooks/useInterview.js`)
- API application → Auth routes: mounts (evidence: `backend/src/app.js`)
- API application → Interview routes: mounts (evidence: `backend/src/app.js`)
- Auth routes → Auth operations: dispatches (evidence: `backend/src/routes/auth.routes.js`)
- Auth routes → Token validation: guards session (evidence: `backend/src/routes/auth.routes.js`)
- Interview routes → Token validation: guards requests (evidence: `backend/src/routes/interview.routes.js`)
- Interview routes → Report operations: dispatches (evidence: `backend/src/routes/interview.routes.js`)
- Auth operations → User records: reads and writes (evidence: `backend/src/controllers/auth.controller.js`)
- Auth operations → Token blacklist: records logout token (evidence: `backend/src/controllers/auth.controller.js`)
- Token validation → Token blacklist: checks token (evidence: `backend/src/middlewares/auth.middleware.js`)
- Report operations → AI generation: generates report (evidence: `backend/src/controllers/interview.controller.js`)
- Report operations → Interview reports: stores and reads (evidence: `backend/src/controllers/interview.controller.js`)
- Report operations → AI generation: generates resume PDF (evidence: `backend/src/controllers/interview.controller.js`)
