rajat-wyrm/quintern

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.