Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Paramount-Intelligence/HR_Monitoring_System/llms.txt

Use this file to discover all available pages before exploring further.

The Workforce Intelligence & Execution OS is built as a modern, full-stack application using a monorepo-style structure. It prioritises relational consistency, role-based security, and background processing for intelligence tasks — with each application tier separated by responsibility and independently deployable on Railway.

​
Monorepo Layout

All application code lives in a single repository partitioned into discrete apps/ and packages/ directories: 
/HR Monitoring System
  /apps
    /web         # Next.js frontend application
    /api         # FastAPI backend application
    /worker      # Celery worker (async tasks, email, reporting)
  /packages
    /ui          # Shared UI components
    /types       # Shared TypeScript type definitions
  /infra         # Infrastructure-as-code / deployment scripts
  /docs          # Project documentation
The apps/api backend code is further organised into a layered structure under apps/api/app: 
/app
  /api            # Route handlers & API logic
    /routes       # Endpoint definitions grouped by module
    /router.py    # Main router registration
  /models         # SQLAlchemy database models
  /schemas        # Pydantic validation schemas
  /services       # Business logic layer
  /core           # Configuration, security, and utilities
  /db             # Session management and migrations
  /worker         # Celery worker and task definitions
  /main.py        # Application entry point
The apps/web frontend lives under apps/web/src with role-scoped route groups: 
/src
  /app
    /(auth)           # Login, Forgot Password, Activate, Reset Password
    /(dashboard)      # Protected dashboard routes
      /admin          # Admin-only views
      /hr             # HR/Operations views
      /manager        # Manager views
      /team-lead      # Team Lead views
      /employee       # Employee views
    /layout.tsx       # Root layout with providers
  /components         # Reusable UI components
  /lib                # Utilities, AuthContext, API client
  /hooks              # Custom React hooks

​
Component Diagram

Every user request flows through the frontend tier before reaching the backend. Long-running work is offloaded asynchronously via Redis and Celery so that the API response is never blocked. 
Users
  │
  ▼
Next.js Frontend  (App Router · TypeScript · Tailwind · shadcn/ui)
  │   HTTPS + JWT
  ▼
FastAPI Backend   (Python · SQLAlchemy · Pydantic)
  │                        │
  ▼                        ▼
PostgreSQL DB          Redis Broker
                           │
                           ▼
                      Celery Worker ──► PostgreSQL DB
                           │
                           ▼
                       SMTP Email Server

​
Technical Stack

Frontend

Next.js (App Router) · TypeScript · Tailwind CSS · shadcn/ui (Radix UI) · Lucide React · React Hook Form + Zod · Axios

Backend

FastAPI (Python) · SQLAlchemy ORM · Pydantic v2 · Alembic migrations · Passlib BCrypt · python-jose JWT

Data & Messaging

PostgreSQL (production) · Redis message broker

Background Processing

Celery worker — email alerts, report generation, periodic metric recalculations

Authentication

JWT — short-lived access tokens (15 min) + long-lived refresh tokens (7 days) stored in the database

Deployment

Railway target platform · Environment-variable-driven configuration via pydantic-settings
PostgreSQL is mandatory in all non-local environments. The backend will raise a hard error at startup if DATABASE_URL resolves to a SQLite connection string.

​
Request Lifecycle

Every HTTP request from the browser travels through eight distinct stages before a response is returned:
1

Client Request

The Next.js frontend sends an HTTPS request with a JWT Authorization: Bearer <access_token> header.
2

API Gateway / CORS

FastAPI’s CORS middleware evaluates the Origin header. Only origins listed in CORS_ORIGINS (plus FRONTEND_BASE_URL) are permitted. In development, localhost:3000–3002 are added automatically.
3

Authentication Middleware

The get_current_user FastAPI dependency decodes and validates the JWT using decode_access_token(). The resolved user object is injected into the request context for downstream handlers.
4

Route Handler

The matching route handler uses Pydantic schemas to validate and deserialise the request body, query parameters, and path variables before any business logic executes.
5

Service Layer

Business logic is fully encapsulated in dedicated service classes (e.g., AttendanceService, LeaveService, AuthService). Routes call services — never the database directly.
6

Database Interaction

SQLAlchemy manages all transactions. Sensitive multi-entity operations (e.g., Leave Request + Approval Timeline) use an atomic flush() → create related entities → commit() pattern so either everything persists or nothing does.
7

Background Tasks

Long-running or non-blocking work — email notifications, metric aggregation, report generation — is enqueued onto Redis and processed by the Celery worker independently of the HTTP response.
8

Response

A standardised JSON response envelope is returned. Errors are mapped to descriptive codes (e.g., VALIDATION_ERROR, AUTH_ERROR, CONFLICT) via centralised exception handlers in main.py.

​
Backend Layered Architecture

Located in /api/routes, this layer:
  • Handles HTTP request/response concerns only.
  • Uses Pydantic schemas for input validation and output serialisation.
  • Enforces RBAC and permission checks via FastAPI dependency injection — never inside service classes.
  • Delegates all business logic to the Service Layer.

​
Data Consistency Patterns

The system enforces data integrity at multiple levels to prevent corruption:
PatternDescription
Atomic TransactionsMulti-entity creations (e.g., Leave Request + Approval Timeline) are wrapped in a single db.flush() + db.commit() transaction. A failure at any point rolls everything back.
Constraint EnforcementForeign key and unique constraints are enforced at the database level, not only in application code, to prevent orphaned or duplicate records regardless of how data is written.
UTC StorageAll timestamps are stored in UTC. Conversion to Asia/Karachi (PKT) happens at display time in the frontend via local date-formatting helpers.

​
Security Architecture

RBAC

Role-Based Access Control is enforced via FastAPI dependencies on every protected route. The service layer additionally applies scope isolation so users can only access data within their hierarchy.

CORS Protection

CORS is restricted to explicitly trusted origins. In production, validate_production_settings() will refuse to start if CORS_ORIGINS is not set or does not include FRONTEND_BASE_URL.

Secrets Management

All secrets (database URLs, SMTP credentials, JWT secret key, API keys) are loaded from environment variables via pydantic-settings. Insecure defaults (change-me-in-env) trigger a hard startup failure in non-development environments.
Never commit .env files to source control. The startup validator (validate_production_settings) will crash the application if APP_SECRET_KEY is set to any of the known-insecure defaults: change-me-in-env, changeme, or secret.
For local development, the backend accepts DATABASE_URL pointing to a Railway-provided PostgreSQL instance. Use pghost, pguser, pgpassword, pgdatabase, and pgport environment variables as an alternative and the settings layer will assemble the full connection string automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us