PharmaHub Pro

GitHub: https://github.com/kevincostner17/hackathon

Evaluator package (single PDF): DELIVERABLES_COMBINED.pdf — overview, architecture figures, schema, AI, security, offline, scaling, integrations, tests, API summary, deployment. Regenerate: ./scripts/build_deliverables_pdf.sh.

PharmaHub Pro is an intelligent pharmacy management MVP: FastAPI microservices, PostgreSQL, Redis/Celery, and a React POS shell. UI and printable invoices show amounts in Indian rupees (INR); stored values are numeric (demo, not FX-converted). It is structured for assessment-style delivery: clear service boundaries, OpenAPI/Swagger on each API, RBAC, offline sync, invoicing, reporting, barcode and ERP integration contracts, and AI features (demand forecasting, sale anomaly scoring, and a manager assistant with optional OpenAI).

Design document: DESIGN.md (architecture detail, RBAC matrix, AI guardrails, ops, integrations, limits). Assessment submission (EC-1–EC-8 crosswalk): SUBMISSION_DESIGN_DOCUMENT.md — PDF with colored flowcharts: SUBMISSION_DESIGN_DOCUMENT.pdf (regenerate: ./scripts/build_submission_pdf.sh). OpenAPI map: docs/openapi.md.

Architecture (Docker / production-shaped)

flowchart LR
  subgraph clients [Clients]
    Browser[Browser_SPA]
  end
  subgraph edge [Host]
    GW[nginx_api_gateway_8080]
    FE[frontend_static_5173]
  end
  subgraph apis [FastAPI_services]
    Auth[auth_8001]
    Inv[inventory_8002]
    Sales[sales_8003]
    AI[ai_8004]
    Int[integrations_8005]
  end
  subgraph data [Data]
    PG[(PostgreSQL)]
    Redis[(Redis)]
  end
  Browser --> FE
  Browser --> GW
  FE -->|"proxies_/api"| GW
  GW --> Auth
  GW --> Inv
  GW --> Sales
  GW --> AI
  GW --> Int
  Auth --> PG
  Inv --> PG
  Sales --> PG
  Sales --> Redis
  AI --> PG
  AI --> Redis
  Int --> PG

Loading

• Single PostgreSQL database for MVP velocity; tables are conceptually domain-scoped (users, inventory, sales, invoices, anomalies, product_barcodes, erp_sync_jobs).
• JWT validated in each API with shared JWT_SECRET.
• Celery: sales_worker (stub batch task), ai_worker (ai.recompute_anomalies).

AI features (implemented)

Capability	API (via gateway)	Code
Demand forecast	GET /api/ai/forecast/{sku} (SMA-style over horizon_days, default 30)	services/ai_service/forecasting.py
Anomaly detection	GET /api/ai/anomalies; POST /api/ai/recompute-anomalies (sync); POST /api/ai/recompute-anomalies/async (Celery)	services/ai_service/anomalies.py, tasks.py
Manager assistant	POST /api/ai/query — heuristic tools over stock/sales/anomalies; optional OpenAI when OPENAI_API_KEY is set on ai_service	services/ai_service/agent.py

The Dashboard tab and AI flows in the UI require manager or super_admin.

Quick start

Without Docker (local all-in-one)

Uses SQLite (pharmahub.local.db) and one FastAPI process on port 8080 (same as the Vite proxy target). This mode exposes a single combined Swagger UI.

cd /path/to/hack
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ./shared_libs
pip install -r requirements-local.txt
python scripts/run_local.py

In a second terminal:

cd frontend && npm install && npm run dev

• UI: http://127.0.0.1:5173
• Swagger (unified): http://127.0.0.1:8080/docs
• Health: http://127.0.0.1:8080/health or http://127.0.0.1:8080/api/health. Readiness (DB): /health/ready and /api/health/ready.

If password hashing errors appear, ensure bcrypt<4.1 (see shared_libs/pyproject.toml).

With Docker

Clean-room (no leftover Postgres volume or local DB state from a previous run):

docker compose down -v
docker compose up --build

Normal start (keeps named volumes):

docker compose up --build

• API gateway: http://localhost:8080 — proxies /api/* to microservices.
• Documentation hub: http://localhost:8080/docs — HTML index with links to per-service Swagger (the gateway does not merge OpenAPI specs).
• Per-service Swagger: http://localhost:8001/docs (auth) … http://localhost:8005/docs (integrations) — see table in docs/openapi.md.
• Frontend (static UI): http://localhost:5173 — proxies /api/* to the gateway.

The auth_service container runs Alembic migrations and scripts.seed before Uvicorn. Other APIs wait on auth_service health (/health/ready) so the schema exists before traffic.

The frontend container serves the SPA and proxies /api/* to api_gateway. If login or checkout fails, check the browser Network tab; 5xx often means a service is still starting.

Demo accounts

Email	Password	Role
super@pharmahub.demo	SuperAdmin123!	super_admin
manager@pharmahub.demo	Manager123!	manager
pharma@pharmahub.demo	Pharma123!	pharmacist

The pharmacist role is limited to inventory and POS checkout; managers see dashboards, reports, and AI endpoints.

Services

Service	Port	Responsibility
auth_service	8001	JWT login, /me
inventory_service	8002	Stock list, batch ingest, expiring alerts, barcodes
sales_service	8003	Checkout, history, offline bulk sync, invoices, reports
ai_service	8004	Forecast, anomalies, manager assistant
integrations_service	8005	ERP sync stub (X-Integration-API-Key)

Workers:

• sales_worker — Celery (MVP stub sales.process_offline_batch)
• ai_worker — Celery ai.recompute_anomalies

Architecture notes

• Offline sync: POST /api/sales/sync with client_local_id for idempotency. Use manager/super_admin JWT, or set SYNC_API_KEY and header X-Sync-Token.
• Super admin price override: PATCH /api/inventory/{id}/price with {"price": 12.99}.
• Invoicing & reports: Checkout/sync create invoices; managers use /api/reports/* (summary, sales-by-day, expiry-risk, top-skus).
• Barcode / ERP: GET /api/inventory/lookup/barcode/{code}; ERP stub at /api/integrations/erp/* with ERP_INTEGRATION_API_KEY.

Assessment scope (explicit)

Not production-hardened: no per-service DB isolation, no full two-phase commit across services, no HA/Kubernetes in this repo. See DESIGN.md.

Production checklist (summary)

• TLS: Terminate HTTPS at the load balancer or ingress; redirect HTTP→HTTPS; consider HSTS.
• CORS: Use explicit admin/POS origins (see cors_allow_origins / service settings).
• Secrets: Use a secret manager; rotate JWT_SECRET, SYNC_API_KEY, ERP_INTEGRATION_API_KEY, and DB credentials.
• Database: Managed PostgreSQL, backups, PITR; run Alembic as part of deploy.
• Rate limiting: Replace in-memory login limiter with Redis (or edge WAF) for multi-replica deployments.
• Observability: Centralize JSON logs with X-Request-ID; metrics/traces per DESIGN.md.

API quick reference

Tables of main routes (gateway or local unified app): docs/API_ENDPOINTS.md. Interactive Swagger: local http://127.0.0.1:8080/docs; Docker hub http://localhost:8080/docs.

Tests & CI

pip install -e ./shared_libs -r requirements-dev.txt
ruff check shared_libs services pharma_local tests scripts
pytest

GitHub Actions (.github/workflows/ci.yml): Ruff, pytest, and frontend production build.

Local development (without Docker)

Install pharma-shared in editable mode, run Postgres/Redis locally, export DATABASE_URL and JWT_SECRET, then run uvicorn from each service directory. Migrations from repo root:

export DATABASE_URL_SYNC=postgresql://pharma:pharma_secret@localhost:5432/pharmahub
pip install -e shared_libs
pip install -r services/auth_service/requirements.txt
alembic upgrade head
python -m scripts.seed

Environment

Copy .env.example to .env for optional local overrides. Docker Compose injects variables directly for the demo.