How mansisonkar1909/goalquest works
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 Server · ai.js AI API · auth.js Auth API · goals.js Goals API
Components 16
API service
Express composition root, route modules, and shared request gate.
- Server · Composition root that configures the API and starts the service.
server.js - DB config · MongoDB connection setup used by the application.
config/db.js - Auth API · Registration, login, and profile endpoints.
routes/auth.js - Goals API · Core goal workflow: create, approve, reject, update, and delete.
routes/goals.js - Users API · Directory and team lookup endpoints for admin and manager flows.
routes/users.js - AI API · Goal suggestions, feedback, and chat backed by Groq LLaMA.
routes/ai.js - Protect · JWT validation and authenticated user context for protected routes.
middleware/protect.js
Domain models
Mongoose-backed application entities and audit trail.
External systems
Outside services consumed by the backend.
- MongoDB Atlas · System of record for users, goals, and audit logs.
- Groq · External LLaMA-powered API used for goal assistance and chat.
- Frontend · Separate client that calls the API with bearer tokens.
- JWT secret · Signing key used for stateless session tokens.
- bcrypt · Password hashing and verification library.
- Express · HTTP server framework used to mount routes and middleware.
Connections 26
- 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.