Criticare Systems – Operations Control Platform

A production-ready MVP that unifies the tender → order → dispatch → installation → after-sales lifecycle for Criticare Systems. The platform comprises a FastAPI backend, PostgreSQL data store (Alembic migrations), and a React + Tailwind front-end that surfaces role-aware queues, actions, and reporting.

🚀 Quick Onboarding Checklist

Follow these steps to get started as a new team member:

1. Get Repository Access

   • Accept the GitHub collaborator invitation sent to your email
   • Verify you can access the repository

2. Clone the Repository

   git clone <repository-url>
   cd "Criticare System Demo-9"

3. Install Docker

   • Install Docker Desktop (4.19+)
   • Ensure Docker is running before proceeding

4. Set Up Environment Variables

   cp .env.example .env
   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env

   • Update the .env files with required values (ask your team lead for environment-specific secrets)

5. Start the Services

   docker compose up --build

   • This will start the database, backend, and frontend services
   • Wait for all containers to be healthy

6. Run Database Migrations

   docker compose exec backend alembic upgrade head

7. Seed Master Data (if needed)

   docker compose exec backend python scripts/seed_master_data.py

8. Verify Everything Works

   • Frontend: Open http://localhost:5174 in your browser
   • Backend API: Visit http://localhost:8001/docs for Swagger documentation
   • Test login with credentials provided by your team lead

Need Help? Contact your team lead or refer to the detailed sections below.

---

Prerequisites

• Docker Desktop 4.19+
• Node.js 20+ (if running the front-end locally without Docker)
• Python 3.11+ (if running backend services locally without Docker)

Environment Setup

cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

• SECRET_KEY must be rotated for each environment.
• STORAGE_DIRECTORY defines where uploaded documents are persisted (default /app/storage, volume-backed).

Development & Local Run

docker compose up --build

Services:

• Frontend SPA → http://localhost:5174
• Backend API / Swagger → http://localhost:8001/docs
• PostgreSQL → postgresql://app_user:app_password@localhost:5433/app_db

Shut down the stack with docker compose down. PostgreSQL data persists inside the named volume postgres-data.

Database & Migrations

Alembic is configured under backend/alembic.

cd backend
alembic upgrade head   # apply migrations
alembic revision -m "description" --autogenerate   # create new migration

First-Time Bootstrap

1. Apply migrations.

2. Start the backend (uvicorn app.main:app --reload or via Docker).

3. Create the first admin account:

   curl -X POST http://localhost:8001/api/auth/bootstrap-admin \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@criticare.in","full_name":"Platform Admin","password":"ChangeMe123","role":"ADMIN"}'

4. Use the admin credentials to sign in through the UI and configure master data:

   • Products, couriers, failure reasons, expense categories, ticket categories.
   • Users across Tender, Back Office, Dispatch, Service Head, Travel Head, Service Engineers.

Testing

Backend unit tests (currently covering service bootstrapping) run via:

cd backend
pytest

Extend the suite under backend/tests as additional behaviours are implemented.

Front-End

The React/Vite app lives in frontend/. It provides:

• Authentication flow (JWT-backed)
• Role-based navigation with queue dashboards for each function
• Master-data consoles (Customers, Products, Couriers, Failure Reasons, Expense & Ticket categories, Users)
• Tender creation/approval linkage to downstream orders
• Order location verification & shipment orchestration (LR uploads, signed LR capture)
• Installation scheduling, engineer execution, travel bookings, expense submission & approvals
• After-sales ticket lifecycle (internal + QR sourced) and reporting exports

Run standalone:

cd frontend
npm install
npm run dev

• Quality gates:

  npm run lint
  npm run build

UI Guide (quick start)

• Dashboard – role-aware queues and alerts.

• Operations – Tenders, Orders, Shipments, Install Tasks, Travel, Expenses, Tickets, Reports.

• Masters – Admin-only management of customers, products, couriers, failure reasons, expense & ticket categories, and user provisioning.

• Every list view shows a clean table; new records are added via the Add … action in the page header (opens a modal form so the workspace stays focused).

• Status transitions that require evidence will prompt for uploads inline; toast notifications confirm success or highlight API errors.

• Use the theme toggle (top-right) to switch between light and dark mode; preferences persist per browser.

• Toast notifications surface API results; every list supports JSON export from the API docs if required.

Key Backend Modules

• app/models/ – SQLAlchemy models (UUID primary keys, auditing, enums).
• app/api/routes/ – REST endpoints organised by domain (auth, masters, tenders, orders, shipments, install tasks, travel, expenses, tickets, queues, reports).
• app/services/ – Business logic enforcing status transitions, document rules, cost aggregation, etc.
• app/core/ – Settings, database session management, security utilities.

Document Storage

Uploads (LRs, signed LRs, travel tickets, completion certificates, expenses) are stored on disk (storage/). The backend validates required document presence when shifting to DISPATCHED, DELIVERED, and DONE.

Reports

/api/reports/sla – Location-level lead-time calculations (dispatch→delivery, delivery→installation).
/api/reports/cost – Order-level expense ledger grouped by category/type.

All report endpoints return JSON that the front-end renders and that can be exported to CSV/Excel downstream.

Authentication & Authorization

• JWT bearer tokens (/api/auth/token)
• Role-based dependency guards implemented via app/core/deps.py
• Admin override endpoints for master data, user administration, and reporting

Production Notes

• Rotate SECRET_KEY per environment and store secrets securely.
• Run Alembic migrations during deployments.
• Mount persistent storage for /app/storage (documents) and PostgreSQL volumes.
• Configure HTTPS terminators / reverse proxies (eg. Traefik, Nginx) in front of the services.
• Extend tests to cover full business workflows as additional features stabilise.

Support

For enhancements or issues:

• Extend domain services & routers following the existing module structure.
• Update front-end pages under frontend/src/pages and shared state via frontend/src/store.
• Regenerate Alembic migrations whenever schema changes are introduced.