Work Management & HR SaaS Platform

Status: 🚧 In Development (T00 Project Bootstrap Complete) Last Updated: 2025-12-27

---

Overview

A Work-Centric HRIS platform designed for Small to Medium Enterprises (10-500 employees). We combine HR management with work management in a single, transparent, and secure platform.

Our unique positioning: More HR-capable than Monday.com, more work-capable than BambooHR, and more affordable than both.

---

Quick Links

Core Documentation

• 📋 Product Requirements (PRD) - Product overview and core features
• 🎯 Product Vision - Strategic positioning and value proposition
• 📦 Product Scope - What's in scope and what's not
• 🚫 Non-Goals - What we will NOT build
• 📖 Glossary - Terminology and definitions
• ⚙️ Tech Rules - Technical stack and architecture constraints
• ✅ Definition of Done - Criteria for feature completion

Strategic Documents

• Vision & Product Strategy (Complete) - Comprehensive strategic foundation

---

Product Vision

"Empower growing teams to manage people and work in one transparent, secure, and intuitive platform."

What We Build

Hybrid HRIS + Work Management platform with:

• ✅ Employee management & organization hierarchy
• ✅ Time tracking & attendance
• ✅ Leave management with approval workflows
• ✅ Task & project management
• ✅ Reporting & compliance
• ✅ Multi-tenant SaaS architecture

What We Don't Build

• ❌ Payroll calculation (partner with providers)
• ❌ Tax compliance logic
• ❌ Recruitment/ATS
• ❌ Learning Management System (LMS)

See non_goals.md for complete list.

---

Technology Stack

Backend

• Framework: FastAPI
• ORM: SQLAlchemy
• Database: PostgreSQL
• Auth: JWT + Refresh Tokens
• Package Manager: Poetry

Frontend

• Framework: React
• Build Tool: Vite
• Language: TypeScript
• State Management: Zustand
• Data Fetching: TanStack Query

DevOps

• Containers: Docker, docker-compose
• Testing: pytest (backend), Vitest (frontend)

See TECH_RULES.md for complete technical constraints.

---

Architecture Principles

1. Modular Monolith (no microservices)
2. Multi-Tenant Isolation (tenant_id in all tables)
3. REST APIs Only (no GraphQL)
4. Security First (RBAC, audit logs, GDPR-ready)
5. Simplicity Over Features (do 10 things excellently)

---

Target Market

Small to Medium Enterprises (SMEs): 10-500 employees

Segment	Size	Primary Needs
Startups/Scale-ups	10-50	Replace Excel, basic HR system, affordable
Mid-Market SMEs	50-200	Consolidate tools, compliance, visibility
Regional Enterprises	200-500	Cost-effective alternative to enterprise solutions

---

Development Roadmap

✅ Milestone 00: Vision & Product Strategy (COMPLETE)

• Product vision and positioning defined
• Scope boundaries established
• Terminology standardized

🔜 Milestone 01: Requirements & MVP Definition

• Detailed functional requirements
• User stories and acceptance criteria
• MVP scope finalization

📅 Future Milestones

• 02: System Architecture
• 03: Database & Data Modeling
• 04: Backend Foundation
• 05: Core HR Features
• 06: Work Management
• 07: Frontend Application
• 08-13: Billing, Security, DevOps, Integrations, Enterprise

See docs/roadmap/ for detailed milestone plans.

---

Getting Started

Prerequisites

• Docker Desktop (with Docker Compose v2)
• Git

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd hr_saas

2. Start all services with Docker Compose

   docker compose up

   This will start:

   • PostgreSQL database on port 5432
   • Backend API on http://localhost:8000
   • Frontend app on http://localhost:3000

3. Access the application

   • Frontend: http://localhost:3000
   • Backend API Docs: http://localhost:8000/api/docs
   • Health Check: http://localhost:8000/health

Development

Backend (FastAPI + Poetry)

cd backend

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run locally (without Docker)
poetry run uvicorn src.main:app --reload

Frontend (React + Vite + TypeScript)

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

# Run linter
npm run lint

# Format code
npm run format

# Type check
npm run type-check

# Build for production
npm run build

Environment Variables

Copy the .env.example files and customize as needed:

# Root level
cp .env.example .env

# Backend
cp backend/.env.example backend/.env

# Frontend
cp frontend/.env.example frontend/.env

Stopping Services

# Stop all services
docker compose down

# Stop and remove volumes (database data)
docker compose down -v

---

Project Structure

hr_saas/
├── .claude/                       # Claude Code project instructions
│   └── CLAUDE.md                  # Task execution rules and guidelines
├── docs/                          # All documentation
│   ├── PRD.md                     # Product Requirements
│   ├── vision.md                  # Product Vision
│   ├── product_scope.md           # Scope Definition
│   ├── non_goals.md               # Explicit Non-Goals
│   ├── GLOSSARY.md                # Terminology
│   ├── TECH_RULES.md              # Technical Constraints
│   ├── DONE_CRITERIA.md           # Definition of Done
│   └── roadmap/                   # Milestone plans
├── tasks/                         # Task definitions by milestone
│   ├── 00-foundation/             # Project bootstrap tasks
│   ├── 01-organization/           # Organization & tenant tasks
│   ├── 02-auth/                   # Authentication tasks
│   ├── 03-employees/              # Employee management tasks
│   ├── 04-time-tracking/          # Time tracking tasks
│   ├── 05-leave/                  # Leave management tasks
│   ├── 06-work/                   # Work management tasks
│   └── 08-audit/                  # Audit logging tasks
├── backend/                       # FastAPI backend
│   ├── src/
│   │   ├── core/                  # Core configuration
│   │   ├── api/                   # API routers
│   │   ├── services/              # Business logic
│   │   ├── repositories/          # Data access layer
│   │   ├── models/                # SQLAlchemy models
│   │   └── schemas/               # Pydantic schemas
│   ├── tests/                     # Backend tests
│   ├── pyproject.toml             # Poetry dependencies
│   ├── Dockerfile                 # Backend Docker image
│   └── .env.example               # Environment variables template
├── frontend/                      # React + Vite frontend
│   ├── src/
│   │   ├── core/                  # Core setup (API, router, query client)
│   │   ├── features/              # Feature modules
│   │   └── shared/                # Shared components and utilities
│   ├── public/                    # Static assets
│   ├── package.json               # NPM dependencies
│   ├── vite.config.ts             # Vite configuration
│   ├── tailwind.config.js         # Tailwind CSS config
│   ├── Dockerfile                 # Frontend Docker image
│   └── .env.example               # Environment variables template
├── docker-compose.yml             # Multi-container orchestration
├── .gitignore                     # Git ignore rules
├── .env.example                   # Root environment template
└── README.md                      # This file

---

Contributing

Current Phase: Foundation & Planning (Milestone 00-01)

Development Workflow (To be established)

1. Read TECH_RULES.md and DONE_CRITERIA.md
2. Follow the modular monolith architecture
3. Ensure all code has type hints (Python) or types (TypeScript)
4. Write tests before marking features complete
5. Document assumptions and decisions

Code Standards

• Backend: Follow FastAPI best practices, service-repository pattern
• Frontend: React functional components, custom hooks, clean separation
• Testing: pytest (backend), Vitest (frontend)
• Commits: Conventional commits (feat:, fix:, docs:, etc.)

---

License

To be determined (Not yet licensed)

---

Contact & Support

Project Status: Early development, not yet accepting external contributions

Documentation Issues: File an issue in the project repository

---

Milestone 00 Completion

Deliverables (All Complete ✅):

• ✅ Clear written product vision (vision.md)
• ✅ Explicit in-scope vs out-of-scope definition (product_scope.md)
• ✅ Non-goals documented (non_goals.md)
• ✅ Terminology consistency established (GLOSSARY.md)
• ✅ Validation against PRD completed
• ✅ All DONE criteria satisfied

Next Milestone: 01 - Requirements & MVP Definition

---

T00 - Project Bootstrap (COMPLETE ✅)

Task: Initialize repository structure, tooling, and baseline configuration

Deliverables (All Complete ✅):

Backend

• ✅ FastAPI application bootstrapped with modular structure
• ✅ Poetry project initialized with dependencies
• ✅ Health check endpoint (/health) implemented and tested
• ✅ Core configuration module with Pydantic Settings
• ✅ Proper folder structure (core, api, services, repositories, models, schemas)
• ✅ pytest configured with test coverage
• ✅ Linting and formatting (ruff, black, mypy) configured
• ✅ Dockerfile for containerization

Frontend

• ✅ React + Vite + TypeScript scaffold created
• ✅ Tailwind CSS configured for styling
• ✅ TanStack Query configured for server state
• ✅ React Router configured for routing
• ✅ Axios API client with interceptors
• ✅ Feature-based folder structure (features, shared, core)
• ✅ ESLint, Prettier, and TypeScript configured
• ✅ Dockerfile for containerization

Infrastructure

• ✅ Docker Compose orchestration (PostgreSQL + Backend + Frontend)
• ✅ PostgreSQL 15 database configured
• ✅ Environment variable templates (.env.example)
• ✅ .gitignore configured for Python, Node, and Docker
• ✅ All services verified running locally

Documentation

• ✅ README updated with setup instructions
• ✅ Project structure documented
• ✅ Development workflow documented

Verification:

• ✅ docker compose up successfully starts all services
• ✅ Backend runs on http://localhost:8000
• ✅ Frontend runs on http://localhost:3000
• ✅ Health endpoint returns correct response
• ✅ Tests pass: poetry run pytest (backend)

Next Task: Tasks in tasks/01-organization/

---

Last Updated: 2025-12-27 Current Task: T00 (Project Bootstrap) ✅ COMPLETE