# mansisonkar1909/goalquest architecture

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

- Interactive diagram: https://gitdiagram.com/mansisonkar1909/goalquest
- Repository: https://github.com/mansisonkar1909/goalquest

## Overview

1. **System shape**
   - This repository is a **single Node.js/Express backend** for GoalQuest.
   - It is a **monolithic REST API** with clear boundaries: HTTP routes, auth middleware, Mongoose models, and a DB connector.
   - The frontend is separate; it consumes this backend over HTTPS using bearer tokens.

2. **Entry point and composition**
   - `server.js` is the composition root.
   - It likely initializes Express, loads environment variables, connects to MongoDB through `config/db.js`, registers route modules, and starts the API server.
   - This is the place where the main subsystems are wired together.

3. **Persistence boundary**
   - `config/db.js` is the only explicit database integration point.
   - The backend uses **Mongoose** against **MongoDB Atlas** as the system of record.
   - The data model is split into three collections: `User`, `Goal`, and `AuditLog`.

4. **Core domain models**
   - `models/User.js` represents identity, role, and authentication-related user profile data.
   - `models/Goal.js` is the main business entity for KPI goals, approvals, quarterly achievements, weights, and lock state.
   - `models/AuditLog.js` captures system actions for traceability, especially useful for admin overrides and approval workflows.

5. **Authentication and session flow**
   - `routes/auth.js` handles register/login/profile lookup.
   - Authentication uses **bcrypt** for password hashing and **JWT** for stateless sessions.
   - The client sends the JWT as a bearer token on protected requests after login.

6. **Authorization boundary**
   - `middleware/protect.js` is the access-control gate for protected APIs.
   - It validates the JWT and exposes the authenticated user context to downstream handlers.
   - Role-based access is enforced at the route level for employee, manager, and admin capabilities.

7. **Goal management workflow**
   - `routes/goals.js` is the core business API.
   - It supports goal creation, approval, rejection, quarterly achievement updates, manager check-ins, and deletion.
   - The workflow is stateful: goals can be edited while pending, then become locked after approval.
   - The route set also distinguishes scope: personal goals, team goals, and org-wide goals.

8. **Organization/user administration**
   - `routes/users.js` provides user-directory style endpoints for admin and manager views.
   - It supports listing all users for admins and team-member lookup for managers.
   - These endpoints are mainly consumed by dashboards and goal-assignment flows.

9. **AI subsystem**
   - `routes/ai.js` is a separate integration boundary for **Groq LLaMA 3.3** features.
   - It powers three AI use cases: goal suggestions, achievement feedback, and GoalBot chat.
   - The route handlers likely assemble prompt context from live user/goal data, then call the external Groq API and return structured results.
   - This subsystem is intentionally isolated from the core CRUD paths so AI failures do not break the rest of the portal.

10. **Auditability and governance**
   - The presence of `AuditLog` indicates the backend is designed for enterprise traceability.
   - Important events such as approvals, rejections, edits, deletions, and overrides are likely recorded.
   - This is a distinct non-functional concern that sits alongside the main goal workflow.

11. **External dependencies and deployment boundaries**
   - External services materially affecting the architecture are **MongoDB Atlas** for persistence, **Groq** for AI, and the **JWT secret** for session security.
   - The backend is intended to run as a standalone service on a platform like **Render**, with a separate frontend deployed elsewhere.
   - The frontend talks to this backend via the `/api/*` routes documented in the README.

12. **What to draw in an architecture diagram**
   - Draw one API service box containing `auth`, `goals`, `users`, and `ai`.
   - Show `protect.js` as a shared security gate in front of protected routes.
   - Show `User`, `Goal`, and `AuditLog` as MongoDB collections behind Mongoose.
   - Show Groq as an external AI dependency only reachable through the AI route module.
   - Show the frontend as an external consumer, not part of this repository’s runtime.

Main entry points: [`server.js`](https://github.com/mansisonkar1909/goalquest/blob/main/server.js) (Server), [`routes/ai.js`](https://github.com/mansisonkar1909/goalquest/blob/main/routes/ai.js) (AI API), [`routes/auth.js`](https://github.com/mansisonkar1909/goalquest/blob/main/routes/auth.js) (Auth API), [`routes/goals.js`](https://github.com/mansisonkar1909/goalquest/blob/main/routes/goals.js) (Goals API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["API service"]
  node_server["Server<br/>express bootstrap<br/>[server.js]"]
  node_db_config["DB config<br/>mongo connector<br/>[db.js]"]
  node_auth_routes["Auth API<br/>route module<br/>[auth.js]"]
  node_goal_routes["Goals API<br/>route module<br/>[goals.js]"]
  node_user_routes["Users API<br/>route module<br/>[users.js]"]
  node_ai_routes["AI API<br/>integration route<br/>[ai.js]"]
  node_protect["Protect<br/>auth middleware<br/>[protect.js]"]
end

subgraph group_group_domain["Domain models"]
  node_user_model[("User<br/>mongoose model<br/>[User.js]")]
  node_goal_model[("Goal<br/>mongoose model<br/>[Goal.js]")]
  node_audit_model[("AuditLog<br/>mongoose model<br/>[AuditLog.js]")]
end

subgraph group_group_external["External systems"]
  node_mongo[("MongoDB Atlas<br/>database")]
  node_groq{{"Groq<br/>ai service"}}
  node_frontend["Frontend<br/>consumer app"]
  node_jwt_secret(("JWT secret<br/>security secret"))
  node_bcrypt(("bcrypt<br/>password hashing"))
  node_express["Express<br/>web framework"]
end

node_server -->|"bootstraps"| node_express
node_server -->|"connects"| node_db_config
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_goal_routes
node_server -->|"mounts"| node_user_routes
node_server -->|"mounts"| node_ai_routes
node_auth_routes -->|"uses"| node_protect
node_goal_routes -->|"uses"| node_protect
node_user_routes -->|"uses"| node_protect
node_ai_routes -->|"uses"| node_protect
node_auth_routes -->|"reads/writes"| node_user_model
node_goal_routes -->|"reads/writes"| node_goal_model
node_goal_routes -->|"records"| node_audit_model
node_user_routes -->|"reads"| node_user_model
node_ai_routes -->|"reads context"| node_user_model
node_ai_routes -->|"reads context"| node_goal_model
node_ai_routes -->|"calls"| node_groq
node_protect -->|"verifies"| node_jwt_secret
node_auth_routes -->|"hashes"| node_bcrypt
node_user_model -->|"persists"| node_mongo
node_goal_model -->|"persists"| node_mongo
node_audit_model -->|"persists"| node_mongo
node_frontend -->|"calls"| node_auth_routes
node_frontend -->|"calls"| node_goal_routes
node_frontend -->|"calls"| node_user_routes
node_frontend -->|"calls"| node_ai_routes

click node_server "https://github.com/mansisonkar1909/goalquest/blob/main/server.js"
click node_db_config "https://github.com/mansisonkar1909/goalquest/blob/main/config/db.js"
click node_auth_routes "https://github.com/mansisonkar1909/goalquest/blob/main/routes/auth.js"
click node_goal_routes "https://github.com/mansisonkar1909/goalquest/blob/main/routes/goals.js"
click node_user_routes "https://github.com/mansisonkar1909/goalquest/blob/main/routes/users.js"
click node_ai_routes "https://github.com/mansisonkar1909/goalquest/blob/main/routes/ai.js"
click node_protect "https://github.com/mansisonkar1909/goalquest/blob/main/middleware/protect.js"
click node_user_model "https://github.com/mansisonkar1909/goalquest/blob/main/models/User.js"
click node_goal_model "https://github.com/mansisonkar1909/goalquest/blob/main/models/Goal.js"
click node_audit_model "https://github.com/mansisonkar1909/goalquest/blob/main/models/AuditLog.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_server,node_db_config,node_auth_routes,node_goal_routes,node_user_routes,node_ai_routes,node_protect toneBlue
class node_user_model,node_goal_model,node_audit_model toneAmber
class node_mongo,node_groq,node_frontend,node_jwt_secret,node_bcrypt,node_express toneMint
```

## Components

### API service

Express composition root, route modules, and shared request gate.

- [Server](https://github.com/mansisonkar1909/goalquest/blob/main/server.js): express bootstrap · Composition root that configures the API and starts the service. · `server.js`
- [DB config](https://github.com/mansisonkar1909/goalquest/blob/main/config/db.js): mongo connector · MongoDB connection setup used by the application. · `config/db.js`
- [Auth API](https://github.com/mansisonkar1909/goalquest/blob/main/routes/auth.js): route module · Registration, login, and profile endpoints. · `routes/auth.js`
- [Goals API](https://github.com/mansisonkar1909/goalquest/blob/main/routes/goals.js): route module · Core goal workflow: create, approve, reject, update, and delete. · `routes/goals.js`
- [Users API](https://github.com/mansisonkar1909/goalquest/blob/main/routes/users.js): route module · Directory and team lookup endpoints for admin and manager flows. · `routes/users.js`
- [AI API](https://github.com/mansisonkar1909/goalquest/blob/main/routes/ai.js): integration route · Goal suggestions, feedback, and chat backed by Groq LLaMA. · `routes/ai.js`
- [Protect](https://github.com/mansisonkar1909/goalquest/blob/main/middleware/protect.js): auth middleware · JWT validation and authenticated user context for protected routes. · `middleware/protect.js`

### Domain models

Mongoose-backed application entities and audit trail.

- [User](https://github.com/mansisonkar1909/goalquest/blob/main/models/User.js): mongoose model · Identity, role, and auth profile data. · `models/User.js`
- [Goal](https://github.com/mansisonkar1909/goalquest/blob/main/models/Goal.js): mongoose model · KPI goals, approvals, quarterly achievements, weights, and lock state. · `models/Goal.js`
- [AuditLog](https://github.com/mansisonkar1909/goalquest/blob/main/models/AuditLog.js): mongoose model · Traceability records for significant actions and overrides. · `models/AuditLog.js`

### External systems

Outside services consumed by the backend.

- **MongoDB Atlas**: database · System of record for users, goals, and audit logs.
- **Groq**: ai service · External LLaMA-powered API used for goal assistance and chat.
- **Frontend**: consumer app · Separate client that calls the API with bearer tokens.
- **JWT secret**: security secret · Signing key used for stateless session tokens.
- **bcrypt**: password hashing · Password hashing and verification library.
- **Express**: web framework · HTTP server framework used to mount routes and middleware.

## Connections

- Server → Express: bootstraps · Creates the HTTP application and mounts handlers.
- Server → DB config: connects · Initializes the MongoDB connection during startup.
- Server → Auth API: mounts · Registers authentication endpoints.
- Server → Goals API: mounts · Registers goal workflow endpoints.
- Server → Users API: mounts · Registers user-directory endpoints.
- Server → AI API: mounts · Registers AI integration endpoints.
- Auth API → Protect: uses · Protected profile and session reads pass through the JWT gate.
- Goals API → Protect: uses · Goal operations require authenticated context.
- Users API → Protect: uses · Admin and manager directory views are access-controlled.
- AI API → Protect: uses · AI requests are executed in authenticated user context.
- Auth API → User: reads/writes · Creates accounts and looks up user profiles.
- Goals API → Goal: reads/writes · Manages goal lifecycle and state transitions.
- Goals API → AuditLog: records · Logs approval, rejection, edits, and overrides.
- Users API → User: reads · Loads users for admin and team views.
- AI API → User: reads context · Uses live user data to build prompts.
- AI API → Goal: reads context · Uses goal data to generate suggestions and feedback.
- AI API → Groq: calls · Sends prompts and receives AI-generated output.
- Protect → JWT secret: verifies · Validates bearer tokens using the signing secret.
- Auth API → bcrypt: hashes · Hashes and compares passwords during auth flows.
- User → MongoDB Atlas: persists · Stored in MongoDB as user documents.
- Goal → MongoDB Atlas: persists · Stored in MongoDB as goal documents.
- AuditLog → MongoDB Atlas: persists · Stored in MongoDB as audit documents.
- Frontend → Auth API: calls · Logs in and fetches profile data.
- Frontend → Goals API: calls · Creates and manages goals through the API.
- Frontend → Users API: calls · Consumes user-directory endpoints.
- Frontend → AI API: calls · Consumes AI assistance features.
