# sivakrishna916/pathforge architecture

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

- Interactive diagram: https://gitdiagram.com/sivakrishna916/pathforge
- Repository: https://github.com/sivakrishna916/pathforge

## Overview

PathForge is a career-discovery product for Indian youth. Users register by education/life-stage segment, take a behavioral quiz, receive trait-based career clusters, and explore real journeys; they can save or upvote stories and submit their own. Admins moderate submissions and view platform and segment analytics. The graph follows the documented workflow and sampled calls; some route wiring and admin analytics implementation are not shown, so those links are left unasserted.

Main entry points: [`client/src/App.jsx`](https://github.com/sivakrishna916/pathforge/blob/main/client/src/App.jsx) (App routing), [`client/src/services/api.js`](https://github.com/sivakrishna916/pathforge/blob/main/client/src/services/api.js) (API client), [`server/src/controllers/quizController.js`](https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/quizController.js) (Quiz handling), [`server/src/controllers/storyController.js`](https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/storyController.js) (Story operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User experience"]
  node_app["App routing<br/>[App.jsx]"]
  node_home["Home and stage<br/>[Home.jsx]"]
  node_dashboard["User dashboard<br/>[Dashboard.jsx]"]
end

subgraph group_identity["Identity"]
  node_auth_ui["Login and register<br/>[Login.jsx]"]
  node_auth_state["Auth state<br/>[AuthContext.jsx]"]
  node_user_data[("User records<br/>[User.js]")]
  node_auth_handler["Authentication handlers<br/>[authController.js]"]
  node_auth_guard["JWT protection<br/>[authMiddleware.js]"]
end

subgraph group_quiz["Career assessment"]
  node_quiz_ui["Quiz experience<br/>[Quiz.jsx]"]
  node_quiz_handler["Quiz handling<br/>[quizController.js]"]
  node_questions[("Quiz questions<br/>[Question.js]")]
  node_scoring["Trait scoring<br/>[scoringService.js]"]
  node_career_insight["Career insight<br/>[geminiService.js]"]
  node_quiz_results[("Quiz results<br/>[QuizResult.js]")]
end

subgraph group_stories["Journey stories"]
  node_stories_ui["Story feed<br/>[Stories.jsx]"]
  node_story_detail["Story detail<br/>[StoryDetail.jsx]"]
  node_submit_ui["Story submission<br/>[Submit.jsx]"]
  node_story_handler["Story operations<br/>[storyController.js]"]
  node_story_rank["Ranked feed pipeline<br/>[aggregations.js]"]
  node_story_data[("Stories<br/>[Story.js]")]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin console<br/>[Admin.jsx]"]
  node_admin_ops["Moderation and analytics<br/>[adminController.js]"]
end

subgraph group_backend["Backend platform"]
  node_api["API client<br/>[api.js]"]
  node_server["Express API<br/>[server.js]"]
  node_db_config["Database connection<br/>[db.js]"]
end

node_visitor(("Student or visitor"))
node_admin_actor(("Administrator"))
node_mongo[("MongoDB")]
node_gemini{{"Gemini service"}}

node_visitor -->|"uses"| node_app
node_admin_actor -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_auth_ui
node_app -->|"routes to"| node_quiz_ui
node_app -->|"routes to"| node_stories_ui
node_app -->|"routes to"| node_story_detail
node_app -->|"routes to"| node_submit_ui
node_app -->|"protects route"| node_dashboard
node_app -->|"guards route"| node_admin_ui
node_auth_ui -->|"updates session"| node_auth_state
node_auth_state -->|"restores session"| node_api
node_auth_ui -->|"calls auth API"| node_api
node_api -->|"sends requests"| node_server
node_server -->|"connects through"| node_db_config
node_db_config -.->|"connects to"| node_mongo
node_server -->|"mounts auth routes"| node_auth_handler
node_auth_handler -->|"reads and writes"| node_user_data
node_server -->|"mounts quiz routes"| node_quiz_handler
node_quiz_handler -->|"loads questions"| node_questions
node_quiz_handler -->|"computes scores"| node_scoring
node_quiz_handler -->|"requests insight"| node_career_insight
node_career_insight -.->|"requests generation"| node_gemini
node_quiz_handler -->|"stores results"| node_quiz_results
node_quiz_ui -->|"submits answers"| node_api
node_quiz_ui -->|"receives recommendations"| node_scoring
node_stories_ui -->|"loads feed"| node_api
node_story_detail -->|"loads story"| node_api
node_submit_ui -->|"submits journey"| node_api
node_admin_ui -->|"requests admin data"| node_api
node_server -->|"mounts story routes"| node_story_handler
node_story_handler -->|"reads and writes"| node_story_data
node_story_handler -->|"updates user saves"| node_user_data
node_story_handler -->|"builds ranked feed"| node_story_rank
node_story_handler -.->|"handles moderation"| node_admin_ops
node_admin_ops -.->|"reviews stories"| node_story_data
node_admin_ops -.->|"reports users"| node_user_data
node_dashboard -->|"loads account data"| node_api

click node_app "https://github.com/sivakrishna916/pathforge/blob/main/client/src/App.jsx"
click node_home "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Home.jsx"
click node_auth_ui "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Login.jsx"
click node_auth_state "https://github.com/sivakrishna916/pathforge/blob/main/client/src/context/AuthContext.jsx"
click node_api "https://github.com/sivakrishna916/pathforge/blob/main/client/src/services/api.js"
click node_quiz_ui "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Quiz.jsx"
click node_quiz_handler "https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/quizController.js"
click node_questions "https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/Question.js"
click node_scoring "https://github.com/sivakrishna916/pathforge/blob/main/server/src/services/scoringService.js"
click node_career_insight "https://github.com/sivakrishna916/pathforge/blob/main/server/src/services/geminiService.js"
click node_quiz_results "https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/QuizResult.js"
click node_stories_ui "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Stories.jsx"
click node_story_detail "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/StoryDetail.jsx"
click node_submit_ui "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Submit.jsx"
click node_story_handler "https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/storyController.js"
click node_story_rank "https://github.com/sivakrishna916/pathforge/blob/main/server/src/utils/aggregations.js"
click node_story_data "https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/Story.js"
click node_user_data "https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/User.js"
click node_dashboard "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Dashboard.jsx"
click node_admin_ui "https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Admin.jsx"
click node_admin_ops "https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/adminController.js"
click node_auth_handler "https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/authController.js"
click node_auth_guard "https://github.com/sivakrishna916/pathforge/blob/main/server/src/middleware/authMiddleware.js"
click node_server "https://github.com/sivakrishna916/pathforge/blob/main/server/server.js"
click node_db_config "https://github.com/sivakrishna916/pathforge/blob/main/server/src/config/db.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_app,node_home,node_dashboard toneBlue
class node_auth_ui,node_auth_state,node_user_data,node_auth_handler,node_auth_guard,node_mongo toneAmber
class node_quiz_ui,node_quiz_handler,node_questions,node_scoring,node_career_insight,node_quiz_results toneMint
class node_stories_ui,node_story_detail,node_submit_ui,node_story_handler,node_story_rank,node_story_data toneRose
class node_admin_ui,node_admin_ops,node_visitor,node_admin_actor,node_gemini toneIndigo
class node_api,node_server,node_db_config toneTeal
```

## Components

### User experience

- [App routing](https://github.com/sivakrishna916/pathforge/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Home and stage](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Home.jsx): `client/src/pages/Home.jsx`
- [User dashboard](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Dashboard.jsx): `client/src/pages/Dashboard.jsx`

### Identity

- [Login and register](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Login.jsx): `client/src/pages/Login.jsx`
- [Auth state](https://github.com/sivakrishna916/pathforge/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [User records](https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/User.js): `server/src/models/User.js`
- [Authentication handlers](https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/authController.js): `server/src/controllers/authController.js`
- [JWT protection](https://github.com/sivakrishna916/pathforge/blob/main/server/src/middleware/authMiddleware.js): `server/src/middleware/authMiddleware.js`

### Career assessment

- [Quiz experience](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Quiz.jsx): `client/src/pages/Quiz.jsx`
- [Quiz handling](https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/quizController.js): `server/src/controllers/quizController.js`
- [Quiz questions](https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/Question.js): `server/src/models/Question.js`
- [Trait scoring](https://github.com/sivakrishna916/pathforge/blob/main/server/src/services/scoringService.js): `server/src/services/scoringService.js`
- [Career insight](https://github.com/sivakrishna916/pathforge/blob/main/server/src/services/geminiService.js): `server/src/services/geminiService.js`
- [Quiz results](https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/QuizResult.js): `server/src/models/QuizResult.js`

### Journey stories

- [Story feed](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Stories.jsx): `client/src/pages/Stories.jsx`
- [Story detail](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/StoryDetail.jsx): `client/src/pages/StoryDetail.jsx`
- [Story submission](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Submit.jsx): `client/src/pages/Submit.jsx`
- [Story operations](https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/storyController.js): `server/src/controllers/storyController.js`
- [Ranked feed pipeline](https://github.com/sivakrishna916/pathforge/blob/main/server/src/utils/aggregations.js): `server/src/utils/aggregations.js`
- [Stories](https://github.com/sivakrishna916/pathforge/blob/main/server/src/models/Story.js): `server/src/models/Story.js`

### Administration

- [Admin console](https://github.com/sivakrishna916/pathforge/blob/main/client/src/pages/Admin.jsx): `client/src/pages/Admin.jsx`
- [Moderation and analytics](https://github.com/sivakrishna916/pathforge/blob/main/server/src/controllers/adminController.js): `server/src/controllers/adminController.js`

### Backend platform

- [API client](https://github.com/sivakrishna916/pathforge/blob/main/client/src/services/api.js): `client/src/services/api.js`
- [Express API](https://github.com/sivakrishna916/pathforge/blob/main/server/server.js): `server/server.js`
- [Database connection](https://github.com/sivakrishna916/pathforge/blob/main/server/src/config/db.js): `server/src/config/db.js`

### Other components

- **Student or visitor**
- **Administrator**
- **MongoDB**
- **Gemini service**

## Connections

- Student or visitor → App routing: uses (evidence: `README.md`)
- Administrator → App routing: uses (evidence: `README.md`)
- App routing → Home and stage: routes to (evidence: `client/src/App.jsx`)
- App routing → Login and register: routes to (evidence: `client/src/App.jsx`)
- App routing → Quiz experience: routes to (evidence: `client/src/App.jsx`)
- App routing → Story feed: routes to (evidence: `client/src/App.jsx`)
- App routing → Story detail: routes to (evidence: `client/src/App.jsx`)
- App routing → Story submission: routes to (evidence: `client/src/App.jsx`)
- App routing → User dashboard: protects route (evidence: `client/src/App.jsx`)
- App routing → Admin console: guards route (evidence: `client/src/App.jsx`)
- Login and register → Auth state: updates session (evidence: `client/src/pages/Login.jsx`)
- Auth state → API client: restores session (evidence: `client/src/context/AuthContext.jsx`)
- Login and register → API client: calls auth API (evidence: `client/src/pages/Login.jsx`)
- API client → Express API: sends requests (evidence: `README.md`)
- Express API → Database connection: connects through (evidence: `server/server.js`)
- Database connection → MongoDB: connects to
- Express API → Authentication handlers: mounts auth routes (evidence: `server/server.js`)
- Authentication handlers → User records: reads and writes (evidence: `server/src/controllers/authController.js`)
- Express API → Quiz handling: mounts quiz routes (evidence: `server/server.js`)
- Quiz handling → Quiz questions: loads questions (evidence: `server/src/controllers/quizController.js`)
- Quiz handling → Trait scoring: computes scores (evidence: `server/src/controllers/quizController.js`)
- Quiz handling → Career insight: requests insight (evidence: `server/src/controllers/quizController.js`)
- Career insight → Gemini service: requests generation
- Quiz handling → Quiz results: stores results (evidence: `server/src/controllers/quizController.js`)
- Quiz experience → API client: submits answers (evidence: `client/src/pages/Quiz.jsx`)
- Quiz experience → Trait scoring: receives recommendations (evidence: `README.md`)
- Story feed → API client: loads feed (evidence: `client/src/pages/Stories.jsx`)
- Story detail → API client: loads story (evidence: `client/src/pages/StoryDetail.jsx`)
- Story submission → API client: submits journey (evidence: `client/src/pages/Submit.jsx`)
- Admin console → API client: requests admin data (evidence: `client/src/pages/Admin.jsx`)
- Express API → Story operations: mounts story routes (evidence: `server/server.js`)
- Story operations → Stories: reads and writes (evidence: `server/src/controllers/storyController.js`)
- Story operations → User records: updates user saves (evidence: `server/src/controllers/storyController.js`)
- Story operations → Ranked feed pipeline: builds ranked feed (evidence: `server/src/controllers/storyController.js`)
- Story operations → Moderation and analytics: handles moderation
- Moderation and analytics → Stories: reviews stories
- Moderation and analytics → User records: reports users
- User dashboard → API client: loads account data (evidence: `client/src/pages/Dashboard.jsx`)
