PHI Service (Python / FastAPI)

• What it is: an umbrella folder ~/development/phi with two implementations of a single healthtech microservice for handling protected health information (PHI) inside Healthcare CRM platform (Saudi/KSA — Vault on vt.ksa.healthcare-platform.com):
• phi-service (Python/FastAPI) — the original implementation (this file focuses on it).
• phi-elysia (TypeScript/Elysia/Bun) — migration/rewrite (with MIGRATION_PLAN.md); covered separately in task #45.
• Type / status / role: api (medical microservice) · active · lead — user is the dominant author (phi-service ~79 commits, phi-elysia 45); team: Alisher Mukhtorov (~28 in phi-service), Anna Shevtsova/aniashev, Harsh Manwani.
• Activity period: phi-service 2025-09-18 → 2026-01-12 (109 commits); phi-elysia 2026-01-05 → 2026-02-12 (57). Active evolution with a Python→Bun/Elysia stack migration.

• phi-service (Python): Python 3.12+, FastAPI + uvicorn, SQLAlchemy 2.0 async + asyncpg + Alembic, Postgres, cryptography + HashiCorp Vault (hvac) for keys, python-jose (JWT), Temporal (temporalio — durable workflows), MinIO (object storage), HL7 (hl7), PDF lab-report parsing (pymupdf, pdf2image, Pillow), Groq/OpenAI (AI interpretation), structlog + python-json-logger + prometheus-client, slowapi (rate-limit), tenacity (retry), httpx. UV (package manager), Docker (+ Dockerfile.worker), Makefile, pytest+xdist+cov, ruff/mypy/bandit.
• phi-elysia (TypeScript, → task #45): Elysia (Bun) + @elysiajs/{jwt,bearer,cors,swagger,opentelemetry}, Temporal (client/worker/workflow) + Inngest (event-driven), Drizzle ORM, MinIO, jose, AWS Secrets Manager, OpenTelemetry + LogTape, Biome.
• Infra/deploy: Docker Compose (dev/prod/inngest variants), a separate worker container, alembic migrations (Python) / drizzle (TS), Vault/Secrets Manager for encryption keys.
• Data: PostgreSQL (encrypted medical data), MinIO (lab-report files/PDFs), Vault (keys). Integration with the PII Service (pseudonymization) and Healthcare CRM platform.

• Secure PHI storage: two-tier encryption (AES-256-GCM + HMAC-SHA256), key management via Vault, pseudonymization (PHI↔PII linkage via a separate PII Service).
• Lab results: PDF result parsing (PyMuPDF/pdf2image), HL7 exchange, converters/workflows in src/labs/{converters,workflows,repositories,services,rest}.
• AI interpretation: versioned result interpretations via Groq/OpenAI.
• Audit: complete access log over medical data.
• Domain modules: labs, medical_profile, health_metrics, chat, ai, partner, authentication, security, external, facades (Onion Architecture).
• Python→Elysia migration (phi-elysia): port to Bun/Elysia + Temporal + Inngest, with test plans (TESTING_PLAN*.md) and IMPLEMENTATION_SUMMARY.
• Volume: 166 total commits (~124 by the user) over ~5 months.

Confirmed by README/CLAUDE/pyproject/structure:

• Two-tier encryption of medical data + Vault (src/security/): AES-256-GCM (confidentiality) + HMAC-SHA256 (integrity/authenticity), keys sourced from HashiCorp Vault rather than env. → Serious cryptography for medical compliance.
• Pseudonymization via PHI/PII separation (src/external/, link to PII Service): medical data is stored separately from identifying data, linked by pseudonyms — a health-privacy pattern (HIPAA/GDPR-class). → Sound privacy architecture.
• Onion Architecture (REST → Facade → Domain Service → Repository): clear layering, cross-domain facades, domain modules with their own models/schemas/dtos/repositories/services. → Mature structure for a large service.
• HL7 + AI interpretation of lab results (src/labs, src/ai): PDF intake → parsing (PyMuPDF) → HL7 → versioned AI interpretation (Groq/OpenAI). → Non-trivial medical data pipeline.
• Durable workflows on Temporal (both implementations): long-running lab-result processing as Temporal workflows (separate worker container) — failure resilience. phi-elysia adds Inngest for event-driven handling.
• Production-grade wiring: Prometheus metrics, structlog (JSON logs), slowapi rate-limit, tenacity retries, bandit security scan, mypy strict, pytest with xdist/coverage. → Operational and quality maturity.

• Sessions found: 2 directories — one for phi-service and one for phi-elysia (subdir form; both implementations were built with Claude Code). .claude/ exists in the umbrella folder as well.
• What was done with AI: the size of CLAUDE.md (phi-service 314 lines!) + migration/test plans (MIGRATION_PLAN, TESTING_PLAN, IMPLEMENTATION_SUMMARY in phi-elysia) point to AI-assisted development and a spec-first process, especially during the Python→Elysia rewrite.
• AI workflow patterns: document-oriented development (a detailed CLAUDE.md as an agent guide), AI-driven stack migration, phased test plans.

• 2 full implementations of the same medical microservice (Python + TypeScript), stack migration.
• ~10 domain modules (labs, medical_profile, health_metrics, chat, ai, security, external, authentication, partner, facades).
• Medical-grade cryptography (AES-256-GCM + HMAC, Vault), HL7, audit.
• 166 commits over ~5 months, a 3–4-person team, the user is the primary author.
• Full CI toolchain (ruff/mypy/bandit/pytest-cov), Prometheus/structlog observability.