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 a monorepo containing a FastAPI backend, a Celery background worker, and a Next.js 15 frontend. This quickstart guide walks you through cloning the repository, configuring your environment, installing dependencies, running all three services, and logging in with the bootstrap admin account.
The default local setup can use SQLite for the database — no PostgreSQL installation is required to get started. To use SQLite, comment out the DATABASE_URL line in your .env file after copying it from .env.example. For a full production-equivalent environment with PostgreSQL, see the Local Development Guide.

​
Prerequisites

Before you begin, ensure the following tools are installed on your machine:
ToolMinimum VersionNotes
Node.jsv18.xv20.x also supported
Python3.10v3.11 also supported
RedisLatest stableRequired for Celery background tasks
GitAny recentFor cloning the repository
PostgreSQL14+Optional locally; comment out DATABASE_URL to use SQLite instead
1

Clone the Repository

Clone the monorepo from GitHub and navigate into the project root:
git clone https://github.com/Paramount-Intelligence/HR_Monitoring_System.git
cd HR_Monitoring_System
2

Configure Environment Variables

Copy the root environment example file to .env in the project root:
cp .env.example .env
Open .env and review these key values before proceeding:
# Required — set a secure random string
APP_SECRET_KEY=change-me-locally

# Database — defaults to PostgreSQL. Comment this line out to use the SQLite fallback instead:
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/workforce_intelligence_utf8

# Bootstrap admin credentials — used to create the first admin user on startup
BOOTSTRAP_ADMIN_EMAIL=[email protected]
BOOTSTRAP_ADMIN_PASSWORD=change-this-password
BOOTSTRAP_ADMIN_NAME="HR Admin"
Never commit your .env file. It contains APP_SECRET_KEY and BOOTSTRAP_ADMIN_PASSWORD which must be treated as secrets in any shared or production environment.
To run locally without PostgreSQL, comment out the DATABASE_URL line in .env. The backend will automatically fall back to a local workforce_intelligence.db SQLite file.
3

Set Up the Backend (API)

Navigate to the API application, create a Python virtual environment, and install all dependencies:
cd apps/api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Key packages installed include fastapi==0.115.0, uvicorn[standard]==0.30.6, sqlalchemy==2.0.35, celery==5.4.0, redis==5.1.1, and alembic==1.13.3.
4

Initialise the Database

With your virtual environment still active and from the apps/api directory, run Alembic migrations to create all tables:
alembic upgrade head
Optionally, seed the database with initial reference data:
python seed.py
The system automatically seeds permissions and bootstraps the default admin user on first API startup using the BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD values from your .env file. You do not need to run seed.py to get a working admin account.
5

Set Up the Frontend

Return to the monorepo root and install all frontend dependencies via npm workspaces:
# From the repository root
cd ../..
npm install
npm workspaces automatically installs dependencies for apps/web and all packages/ in a single command.
6

Start the API Server

Open a new terminal. Navigate to apps/api, activate your virtual environment, and start the FastAPI server:
cd apps/api
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8080
The API will be available at http://localhost:8080. The interactive API docs (Swagger UI) are at http://localhost:8080/docs.
7

Start the Background Worker

Open a third terminal. Navigate to apps/api, activate your virtual environment, and start the Celery worker:
cd apps/api
source venv/bin/activate
celery -A app.worker worker --loglevel=info
Redis must be running before starting the Celery worker. If Redis is not running, the worker will fail to connect. Start Redis with redis-server or via Docker: docker run -p 6379:6379 redis.
The --pool=solo flag is recommended on Windows to avoid multiprocessing issues. It is not required on macOS or Linux.
8

Start the Frontend

From the monorepo root, start the Next.js development server:
# From the repository root
npm run dev:web
Alternatively, start it directly from the web app directory:
cd apps/web
npm run dev
The web application will be available at http://localhost:3000.
9

Log In with the Bootstrap Admin

Open your browser and navigate to http://localhost:3000. Log in using the bootstrap admin credentials you set in your .env file:
Email:    [email protected]       # BOOTSTRAP_ADMIN_EMAIL
Password: change-this-password    # BOOTSTRAP_ADMIN_PASSWORD
After your first login, immediately navigate to Admin → Profile to update the bootstrap admin’s password. The default credentials in .env.example are public and should not remain in use.

​
What’s Running

Once all services are started, you will have three processes running:
ServiceURLDescription
Next.js Frontendhttp://localhost:3000Role-based dashboards and UI
FastAPI Backendhttp://localhost:8080REST API + WebSocket server
Swagger UIhttp://localhost:8080/docsInteractive API documentation
Celery Worker—Background jobs (alerts, reports)
Redisredis://localhost:6379/0Message broker for Celery

​
Next Steps

Local Development Guide

Full environment variable reference, database seeding, linting commands, and common error fixes.

System Architecture

Understand how the backend, frontend, worker, and database fit together.

Roles & Permissions

Invite your first users and assign roles via the Admin panel.

API Overview

Explore all available REST endpoints in the interactive Swagger docs.

Build docs developers (and LLMs) love

Get started for freeTalk to us