A full-stack platform to manage Comprehensive Osteosynthesis Service contracts between a medical supply company and multiple Mexican state government healthcare agencies (IMSS and others). The system digitizes and controls the full surgical event lifecycle — from material request to government invoicing — eliminating manual tracking, reducing documentation errors, and enabling monthly contract billing through structured Excel exports. In production from September 2025 to May 2026 across 15 hospitals, 10 users, 2 states.
Architecture & Stack
Multi-service containerized architecture orchestrated via Docker Compose with environment-specific configurations (dev, QA, prod).
Angular 19 (Tailwind + PrimeNG) — Firebase Hosting ↓ (Socket.IO / REST)FastAPI REST API + Nginx + Gunicorn ↓ Services → Repositories → Beanie ODM ↓ MongoDB ↓ Celery Workers (RabbitMQ broker) ↓ GCP Compute Engine — Docker Compose GCP Cloud Storage (PDF uploads) Terraform (infrastructure as code)- Backend — FastAPI (Python 3.11) in a strict layered pattern (Endpoints → Services → Repositories → ODM)
- Database — MongoDB via Beanie ODM (async Motor driver) with document-level caching
- Async tasks — Celery with RabbitMQ (QA/prod) or Redis (dev), priority queues (high/default/low)
- Real-time — Task status pushed to clients via Socket.IO (Redis pub/sub manager)
- Storage — Google Cloud Storage for PDF uploads (prescriptions, CURP, INE, remission sheets)
- Frontend — Angular 19 SPA with Tailwind CSS and PrimeNG, hosted on Firebase, authenticated via Firebase Auth with Microsoft 365 Enterprise SSO
- Infrastructure — Terraform-provisioned GCP + Firebase; GitHub Actions CI/CD (quality checks → Docker build → automated deploy to GCP Compute Engine)
- Observability — Prometheus + Grafana + Alertmanager + cAdvisor + Node Exporter + Pushgateway behind Caddy, plus Papertrail for logs and Sentry for error monitoring
Key Technical Achievements
Domain modeling — A multi-contract, multi-agency domain covering tiered commission schemes (retroactive/progressive, configurable tiers with per-surgery monetary value), surgical materials tagged with SAT fiscal keys and CCNIS codes for government invoicing, multi-type patient identification (CURP, IMSS NSS), and per-contract document requirements — all with soft-delete and slugs to prevent duplicates across catalog entities.
Surgical event workflow — An 8-step lifecycle: material request → purchasing approval (with external-material substitution) → warehouse dispatch with ERP reference tracking → instrument receipt confirmation → post-surgery data capture → PDF document upload → material remission → supervisor validation. Supervisor-validated events feed a monthly Excel export with full material consumption detail per contract for government invoicing.
Clean layered architecture — Endpoints → Services → Repositories → ODM with dependency injection via FastAPI’s Depends(get_services); a custom exception hierarchy (BaseAppException → DatabaseException, BusinessLogicException, AuthException) handled by a global ExceptionMiddleware; role-based access control with role-specific dashboards and reports.
Production resilience — pytest suite with unit tests (mocked repositories via AsyncMock) and integration tests against a live isolated test database; non-root Docker containers behind Nginx and Gunicorn; every data model carries created_at/updated_at/soft-delete fields for full data pipeline compatibility.