# rajat-wyrm/quintern architecture

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

- Interactive diagram: https://gitdiagram.com/rajat-wyrm/quintern
- Repository: https://github.com/rajat-wyrm/quintern

## Overview

1. **Overall shape**
   Quintern is a two-tier application: a **React/Vite frontend** and a **Fastify/Node backend**, backed by **PostgreSQL** and **Redis**. The backend exposes REST APIs, a Socket.IO realtime channel, and a few external webhooks/integration endpoints. The frontend is a single-page app that talks to those APIs and subscribes to realtime updates.

2. **Primary business domain**
   The core domain is a **5-level hierarchy**: Admin → Senior TL → TL → Captain → Intern. This is not just UI metadata; it drives access control, data visibility, and who can act on whom across attendance, ratings, tasks, teams, and reports. Most server modules exist to enforce or operate within that hierarchy.

3. **Backend structure**
   The backend is organized as **feature modules** under `backend/src/modules`, each with its own routes and usually a repository/service layer. Shared concerns live in `config`, `middleware`, `utils`, and `services`. `app.js` is the Fastify entry point that wires plugins, auth, routes, metrics, and realtime into one process.

4. **Data layer**
   PostgreSQL is the system of record. Schema changes are managed by SQL migrations in `backend/migrations`, covering users, departments, hierarchy relations, attendance, ratings, tasks/proofs, meetings, notifications, audit logs, sessions, uploads-related metadata, and integration event tables. The database is also the main enforcement point for normalized relationships and immutable records like ratings and audit entries.

5. **Security and authorization boundary**
   Request handling is layered: **JWT auth**, then **RBAC**, then **ownership/hierarchy checks**, plus **direct-manager checks** where needed. There is also **CSRF protection** for state-changing browser requests, **brute-force throttling** on login, and parameterized SQL throughout. This means most endpoints are not just role-protected; they are relationship-aware.

6. **Main business modules**
   The highest-traffic modules are likely `auth`, `users`, `hierarchy`, `team`, `attendance`, `ratings`, `social-tasks`, `proof-submissions`, `meetings`, `notifications`, `projects`, `reports`, and `analytics`. These are the core operational flows: user lifecycle, org structure, daily attendance, performance ratings, task proof submission, meeting coordination, dashboards, and exports.

7. **Realtime subsystem**
   Realtime is handled by a dedicated Socket.IO module and a backend socket bootstrap. Clients connect with a JWT in the handshake, then are placed into rooms such as user-, role-, department-, or global-scoped channels. The realtime layer pushes notifications and domain events like attendance changes, ratings, meeting creation, and task updates, and the frontend uses those events to invalidate cached queries and show toasts.

8. **AI assistant subsystem**
   The AI module is a separate bounded context. It exposes assistant/chat and insights/search-style endpoints and uses a **fallback chain across multiple providers** before dropping to a local heuristic response. This subsystem is role-aware, meaning the prompt/context changes based on whether the caller is an admin, manager, or intern. It is isolated from the rest of the app through its own routes and service layer.

9. **External integrations**
   There are three notable external service boundaries:
   - **Cloudinary** for avatar and file uploads, with local-disk fallback if cloud config or upload fails.
   - **Stripe** for webhook ingestion and event storage, with raw-body HMAC verification.
   - **Uptoskills** for external sync status/integration.
   Redis is also used as an infrastructure dependency for rate limiting, token/session-related caching, and other hot-path state.

10. **Frontend architecture**
   The frontend is a route-based SPA with about two dozen pages, including public auth pages and authenticated views for dashboard, team, attendance, ratings, tasks, meetings, notifications, assistant, sessions, reports, analytics, admin, departments, audit, and exports. Shared UI lives in a large custom component library, while app state is split between **Zustand** for auth/session and **TanStack Query** for server state and cache invalidation.

11. **Client/server interaction pattern**
   Typical flows are: the user logs in via REST, receives access/refresh tokens, then the frontend fetches server data through query hooks. For live updates, `SocketBridge` connects the socket, listens for domain events, and refreshes affected cached queries. This makes the UI reactive without relying on polling.

12. **Operations, reliability, and observability**
   The repo is built for deployability: Dockerfiles exist for both tiers, compose files define local and production stacks, and the README points to Vercel, Render, Neon, and Upstash as the intended hosting split. Observability includes **Pino logs**, **Prometheus metrics**, and health/ready endpoints. CI runs formatting, tests, a smoke pass, and release packaging, which makes the architecture production-oriented rather than prototype-only.

13. **Testing and seed model**
   The backend has Jest integration tests and deterministic seed scripts. The seed data reflects the domain model: multiple roles, departments, and related entities so the hierarchy and permissions can be exercised realistically. Diagnostic scripts also exist for provider checks and socket connectivity, which reinforces that AI and realtime are first-class subsystems.

14. **How to diagram it**
   If you’re drawing the architecture, treat the backend as the central hub with these outbound edges: PostgreSQL for durable state, Redis for fast ephemeral state, Socket.IO for live updates, Cloudinary for uploads, Stripe for payment events, AI providers for assistant responses, and email services for auth/notification flows. The frontend should be shown as a thin client consuming REST plus realtime, with auth/session state and query cache acting as its main local state boundary.

Main entry points: [`backend/src/app.js`](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/app.js) (Server app), [`backend/migrations/001_initial.sql`](https://github.com/rajat-wyrm/quintern/blob/main/backend/migrations/001_initial.sql) (PostgreSQL), [`frontend/src/pages`](https://github.com/rajat-wyrm/quintern/tree/main/frontend/src/pages) (App pages), [`backend/src/modules/team/routes.js`](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/team/routes.js) (Ops modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["SPA shell<br/>React/Vite app<br/>[App.jsx]"]
  node_fe_state(("Client state<br/>Zustand + Query<br/>[auth.js]"))
  node_fe_socket(("Socket bridge<br/>Realtime client<br/>[SocketBridge.jsx]"))
  node_fe_pages["App pages<br/>Views"]
  node_fe_ui["UI kit<br/>Shared components<br/>[ui.jsx]"]
end

subgraph group_backend["Backend"]
  node_be_app["Server app<br/>Fastify entry<br/>[app.js]"]
  node_be_security["Security layer<br/>Middleware<br/>[auth.js]"]
  node_be_auth["Auth module<br/>Identity<br/>[routes.js]"]
  node_be_users["Users module<br/>People<br/>[routes.js]"]
  node_be_hierarchy["Hierarchy module<br/>Org rules<br/>[routes.js]"]
  node_be_ops["Ops modules<br/>Workflows<br/>[routes.js]"]
  node_be_ai["AI assistant<br/>LLM context<br/>[routes.js]"]
  node_be_rt(("Realtime hub<br/>Socket.IO<br/>[io.js]"))
  node_be_uploads["Uploads<br/>File handling<br/>[cloudinary.js]"]
  node_be_integrations["External webhooks<br/>Inbound integrations<br/>[routes.js]"]
  node_be_email["Email service<br/>Notifications<br/>[email.js]"]
end

subgraph group_infra["Data & integrations"]
  node_db_pg[("PostgreSQL<br/>System of record<br/>[001_initial.sql]")]
  node_cache_redis[("Redis<br/>Cache<br/>[redis.js]")]
  node_svc_cloudinary[("Cloudinary<br/>Media storage<br/>[cloudinary.js]")]
  node_svc_stripe[("Stripe<br/>Payment webhooks<br/>[routes.js]")]
  node_svc_uptoskills[("Uptoskills<br/>External sync<br/>[service.js]")]
end

node_fe_app -->|"routes"| node_fe_pages
node_fe_app -->|"composes"| node_fe_ui
node_fe_pages -->|"queries"| node_fe_state
node_fe_state -.->|"refreshes"| node_fe_socket
node_fe_socket -->|"connects"| node_be_rt
node_fe_pages -->|"REST"| node_be_app
node_be_app -->|"guards"| node_be_security
node_be_app -->|"routes"| node_be_auth
node_be_app -->|"routes"| node_be_users
node_be_app -->|"routes"| node_be_hierarchy
node_be_app -->|"routes"| node_be_ops
node_be_app -->|"routes"| node_be_ai
node_be_app -->|"routes"| node_be_uploads
node_be_app -->|"webhooks"| node_be_integrations
node_be_app -->|"uses"| node_be_email
node_be_auth -->|"reads/writes"| node_db_pg
node_be_users -->|"reads/writes"| node_db_pg
node_be_hierarchy -->|"reads/writes"| node_db_pg
node_be_ops -->|"reads/writes"| node_db_pg
node_be_ops -->|"publishes"| node_be_rt
node_be_ai -->|"reads"| node_db_pg
node_be_uploads -->|"uploads"| node_svc_cloudinary
node_be_uploads -->|"metadata"| node_db_pg
node_be_integrations -->|"ingests"| node_svc_stripe
node_be_integrations -->|"syncs"| node_svc_uptoskills
node_be_security -->|"throttles"| node_cache_redis
node_be_app -->|"caches"| node_cache_redis
node_be_email -.->|"templates"| node_db_pg

click node_fe_app "https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/App.jsx"
click node_fe_state "https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/store/auth.js"
click node_fe_socket "https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/components/SocketBridge.jsx"
click node_fe_pages "https://github.com/rajat-wyrm/quintern/tree/main/frontend/src/pages"
click node_fe_ui "https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/components/ui.jsx"
click node_be_app "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/app.js"
click node_be_security "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/middleware/auth.js"
click node_be_auth "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/auth/routes.js"
click node_be_users "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/users/routes.js"
click node_be_hierarchy "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/hierarchy/routes.js"
click node_be_ops "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/team/routes.js"
click node_be_ai "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/ai/routes.js"
click node_be_rt "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/realtime/io.js"
click node_be_uploads "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/uploads/cloudinary.js"
click node_be_integrations "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/stripe/routes.js"
click node_be_email "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/services/email.js"
click node_db_pg "https://github.com/rajat-wyrm/quintern/blob/main/backend/migrations/001_initial.sql"
click node_cache_redis "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/config/redis.js"
click node_svc_cloudinary "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/uploads/cloudinary.js"
click node_svc_stripe "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/stripe/routes.js"
click node_svc_uptoskills "https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/uptoskills/service.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_fe_app,node_fe_state,node_fe_socket,node_fe_pages,node_fe_ui toneBlue
class node_be_app,node_be_security,node_be_auth,node_be_users,node_be_hierarchy,node_be_ops,node_be_ai,node_be_rt,node_be_uploads,node_be_integrations,node_be_email toneAmber
class node_db_pg,node_cache_redis,node_svc_cloudinary,node_svc_stripe,node_svc_uptoskills toneMint
```

## Components

### Frontend

React/Vite single-page client

- [SPA shell](https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/App.jsx): React/Vite app · Route-based client entry and layout composition · `frontend/src/App.jsx`
- [Client state](https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/store/auth.js): Zustand + Query · Auth/session store and server-state cache · `frontend/src/store/auth.js`
- [Socket bridge](https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/components/SocketBridge.jsx): Realtime client · JWT-authenticated Socket.IO connection and query refreshes · `frontend/src/components/SocketBridge.jsx`
- [App pages](https://github.com/rajat-wyrm/quintern/tree/main/frontend/src/pages): Views · Public auth, dashboard, team, attendance, tasks, reports, admin, and assistant views · `frontend/src/pages`
- [UI kit](https://github.com/rajat-wyrm/quintern/blob/main/frontend/src/components/ui.jsx): Shared components · Reusable forms, tables, charts, and layout components · `frontend/src/components/ui.jsx`

### Backend

Fastify API and feature modules

- [Server app](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/app.js): Fastify entry · Wires plugins, routes, auth, metrics, and realtime · `backend/src/app.js`
- [Security layer](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/middleware/auth.js): Middleware · JWT auth, RBAC, ownership, direct-manager, CSRF, brute-force, and sanitization · `backend/src/middleware/auth.js`
- [Auth module](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/auth/routes.js): Identity · Login, reset, verification, and token/session flows · `backend/src/modules/auth/routes.js`
- [Users module](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/users/routes.js): People · User lifecycle and profile operations · `backend/src/modules/users/routes.js`
- [Hierarchy module](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/hierarchy/routes.js): Org rules · Admin through intern hierarchy and relationship logic · `backend/src/modules/hierarchy/routes.js`
- [Ops modules](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/team/routes.js): Workflows · Team, attendance, ratings, tasks, meetings, notifications, projects, reports, and analytics · `backend/src/modules/team/routes.js`
- [AI assistant](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/ai/routes.js): LLM context · Chat and insights endpoints with provider fallback and role-aware prompts · `backend/src/modules/ai/routes.js`
- [Realtime hub](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/realtime/io.js): Socket.IO · Room-based event broadcast for live domain updates · `backend/src/modules/realtime/io.js`
- [Uploads](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/uploads/cloudinary.js): File handling · Avatar and file upload pipeline with cloud/local fallback · `backend/src/modules/uploads/cloudinary.js`
- [External webhooks](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/stripe/routes.js): Inbound integrations · Stripe webhook ingestion and Uptoskills sync · `backend/src/modules/stripe/routes.js`
- [Email service](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/services/email.js): Notifications · Templates and outbound verification/reset/notification mail · `backend/src/services/email.js`

### Data & integrations

Persistent storage, cache, and external services

- [PostgreSQL](https://github.com/rajat-wyrm/quintern/blob/main/backend/migrations/001_initial.sql): System of record · Primary relational store for users, hierarchy, attendance, ratings, tasks, meetings, notifications, audit, sessions, and integrations · `backend/migrations/001_initial.sql`
- [Redis](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/config/redis.js): Cache · Rate limiting, session/token hot state, and ephemeral coordination · `backend/src/config/redis.js`
- [Cloudinary](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/uploads/cloudinary.js): Media storage · Hosted avatar and file uploads · `backend/src/modules/uploads/cloudinary.js`
- [Stripe](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/stripe/routes.js): Payment webhooks · Payment and event webhook source · `backend/src/modules/stripe/routes.js`
- [Uptoskills](https://github.com/rajat-wyrm/quintern/blob/main/backend/src/modules/uptoskills/service.js): External sync · Integration status and sync boundary · `backend/src/modules/uptoskills/service.js`

## Connections

- SPA shell → App pages: routes · Renders the application views
- SPA shell → UI kit: composes · Uses shared UI components
- App pages → Client state: queries · Reads and caches server state
- Client state → Socket bridge: refreshes · Invalidates cached data on realtime events
- Socket bridge → Realtime hub: connects · Socket.IO client channel with JWT handshake
- App pages → Server app: REST · Fetches API data and mutates state
- Server app → Security layer: guards · Applies auth and relationship-aware request checks
- Server app → Auth module: routes · Login, reset, and verification endpoints
- Server app → Users module: routes · User and profile endpoints
- Server app → Hierarchy module: routes · Org structure and access relationships
- Server app → Ops modules: routes · Core operational modules
- Server app → AI assistant: routes · Assistant and insights endpoints
- Server app → Uploads: routes · File upload endpoints
- Server app → External webhooks: webhooks · External event ingestion endpoints
- Server app → Email service: uses · Sends verification, reset, and notification mail
- Auth module → PostgreSQL: reads/writes · Credentials, sessions, and verification records
- Users module → PostgreSQL: reads/writes · User profile data
- Hierarchy module → PostgreSQL: reads/writes · Hierarchy and department relations
- Ops modules → PostgreSQL: reads/writes · Attendance, ratings, tasks, meetings, reports, and analytics data
- Ops modules → Realtime hub: publishes · Emits live domain events
- AI assistant → PostgreSQL: reads · Uses stored context and access data
- Uploads → Cloudinary: uploads · Primary media storage boundary
- Uploads → PostgreSQL: metadata · Persists upload references
- External webhooks → Stripe: ingests · Verifies and stores webhook events
- External webhooks → Uptoskills: syncs · External integration status flow
- Security layer → Redis: throttles · Brute-force and hot-path limits
- Server app → Redis: caches · Uses Redis for ephemeral server state
- Email service → PostgreSQL: templates · Notification and account lifecycle mail data