An automated scheduling and shift optimization platform designed for hospital clinics (such as the Louis Pasteur University Hospital). The system balances staff availability, specialized qualifications, and complex clinical constraints using Mathematical Optimization.
The application streamlines clinical scheduling by dividing the workflow into two major pillars:
- Core Administration & Tracking (Phase 1):
- Employees: Log in to submit their unavailabilities and manage their medical qualifications.
- Clinic Managers: Oversee specific clinics, manually adjust schedules, and manage staff constraints.
- Automated Optimization (Phase 2):
- Uses a Linear Programming (LP) solver to automatically construct optimal monthly or weekly shift schedules, fully respecting employee unavailabilities and required clinical credentials.
- Frontend: React, Vite, TypeScript, Zustand (State Management), Axios
- Backend: Python (FastAPI), SQLAlchemy (ORM), Alembic (Migrations)
- Database: PostgreSQL
- Containerization: Docker & Docker Compose
├── .agents/
│ └── rules/ # Custom behavioral guidelines for AI development agents
├── backend/
│ ├── app/
│ │ ├── api/ # FastAPI REST endpoints
│ │ ├── models/ # SQLAlchemy ORM models
│ │ ├── schemas/ # Pydantic data validation and serialization
│ │ └── services/ # Core business logic and LP optimization algorithms
│ └── database/ # DB engine sessions and migrations
├── frontend/
│ └── src/
│ ├── api/ # API client configurations (Axios)
│ ├── components/ # Reusable UI component library
│ ├── stores/ # Global application state (Zustand)
│ └── views/ # Page layouts (Manager Board, Calendars)
├── docker-compose.yml # Orchestrates Python, React, and PostgreSQL containers
└── CONTEXT.md # Global technical architectural context
The easiest way to run the entire stack (React frontend, FastAPI backend, and PostgreSQL database) is using Docker Compose.
Make sure you have Docker and Docker Compose installed on your system.
- Clone the repository and navigate to the root directory:
git clone <repository-url>
cd scheduling
Copy the environment template and replace the placeholder password and secret:
Copy-Item .env.example .env- Build and start the containers in detached mode (PowerShell):
.\start.ps1 -Detached
This command automatically:
- Builds the React frontend container.
- Builds the Python FastAPI backend container.
- Retries one transient Docker BuildKit snapshot failure automatically.
- Applies pending Alembic database migrations before the backend starts.
- Pulls and initializes the PostgreSQL database.
- Links them all under a single shared network.
- Verify the services are running:
docker compose ps
- Access the applications:
- Frontend (React UI): http://localhost:3000 (or the port specified in your
docker-compose.yml) - Backend API Docs (Swagger UI): http://localhost:8000/docs
To stop and remove all containers, networks, and associated volumes:
docker compose down -v
If you are modifying this project or using an AI developer agent (like Antigravity), you must strictly adhere to the contracts defined in .agents/rules/:
global.md: Enforces strict English code, docstrings, type hinting, and structural modularity.backend.md: Mandates a strict 1:1:1 domain decoupling (SQLAlchemy Models ↔ Pydantic Schemas ↔ FastAPI Routers).database.md: Outlines transaction safety boundaries and Alembic migration protocols.
The backend startup runs the database bootstrap before Uvicorn. Schema creation is always safe to run, while deterministic mock data is updated only when explicitly enabled:
AUTO_SEED=true
SEED_CONFIG=config_1Each seed profile declares a version. The backend stores applied versions in
seed_versions and skips an already-current profile. Increment the profile's
version whenever its data changes. Keep AUTO_SEED=false (the default) for
production databases; enable it only for CI, preview, test, or controlled demo
environments.
database-schema.md: Defines the exact relational database layout.