An internal HR tool for viewing and managing employee salary records. HR users log in via OTP, manage employee data, update salaries with full history tracking, and query salary data using natural language.
EmployeeManagementSystem/
├── ems-service/ # FastAPI backend (Python 3.12+)
├── ems-client/ # React frontend (Node 18+)
└── artifacts/ # Design documents
Python FastAPI backend. Handles authentication, user management, employee records, salary history, reference data (departments / countries / job titles), rate limiting, and an LLM-powered chat endpoint.
→ Full setup guide: ems-service/README.md
React + TypeScript frontend. Three tabs: employee salary management grid, a natural language assistant, and an admin panel for managing HR Manager accounts.
→ Full setup guide: ems-client/README.md
Before starting either service you need three things running:
| Service | Purpose |
|---|---|
| PostgreSQL | Primary database — employees, users, salary history |
| Redis | Rate limiting counters + user cache |
| SMTP account | Sending OTP login emails (Gmail works) |
Follow this order — the backend must be running before the frontend makes any API calls.
cd ems-service
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.sample .env.development # fill in Postgres, Redis, SMTP, JWT secret, LLM key
python -m src.scripts.migrate # create tables
python -m src.scripts.seed.run # seed reference data + create admin user
uvicorn src.main:app --reload --port 8000Full variable reference and details → ems-service/README.md
cd ems-client
npm install
cp .env.sample .env.development # set VITE_API_URL and VITE_AGG_LICENSE
npm run devFull variable reference and details → ems-client/README.md
Open http://localhost:5173. Log in with the admin username you created during seeding.
| Role | What they can do |
|---|---|
| Admin | Everything — manage HR Manager accounts + all employee operations |
| HR Manager | All employee operations, salary updates, and the assistant. Cannot manage users. |
The Admin account is created once during seed.run. It cannot be deleted or modified.
The artifacts/ folder contains the full design history for the project:
| File | Contents |
|---|---|
0. Clarifications.md |
Initial scope questions and answers |
1. Requirements.md |
Full feature requirements and out-of-scope items |
2. High Level Design.md |
Architecture, data model, API design |
3. Deep Dive Backend.md |
Backend internals — auth, RBAC, rate limiting, LLM layer |
4. Deep Dive Frontend.md |
Frontend internals — routing, state, pages, service layer |
5. Wrap Up.md |
Design vs reality, trade-offs, known gaps, scaling notes |