### Technology Stack
- **Framework:** FastAPI (Python)
- **Database:** PostgreSQL + pgvector
- **Cache:** Redis
- **Task Queue:** Celery/RabbitMQ (for async STT and AI processing)
- **AI Engines:** Whisper (Self-hosted), Llama/Mistral (Self-hosted)

---

## Production Readiness Overview
This structure is built to **Production Grade** standards for healthcare applications:
- **Scalability:** The Monolithic Modular approach allows modules to be extracted into microservices if needed, while maintaining shared logic in `shared/`.
- **Security:** Built-in layers for JWT OAuth2, AES-256 encryption, and HIPAA-compliant data masking.
- **Observability:** Centralized JSON logging and audit trails in `shared/utils/hipaa_logger.py`.
- **Reliability:** Async DB sessions and background task workers (Celery) prevent request blocking during heavy AI processing.
- **Maintainability:** Clear separation of concerns mapping directly to business domains (Claim, Billing, Patient).

---

## 1. Directory Tree Overview

```text
iam_billy_backend/
├── app/                        # Main Application Package
│   ├── main.py                 # App entry point & middleware
│   ├── api/                    # API Experience Layer
│   │   ├── dependencies.py     # Global FastAPI dependencies
│   │   └── v1/                 # Versioned API routes
│   │       └── api.py          # Main router inclusion
│   ├── core/                   # Global System Core
│   │   ├── config.py           # Settings (Pydantic)
│   │   ├── security.py         # Auth (JWT/OAuth2) logic
│   │   └── exceptions.py       # Global error handlers
│   ├── database/               # Data Access Layer
│   │   ├── base.py             # SQLAlchemy model registry
│   │   ├── session.py          # DB Engine & Session factory
│   │   └── migrations/         # Alembic migration scripts
│   │       ├── env.py
│   │       ├── script.py.mako
│   │       └── versions/       # Individual migration files
│   ├── modules/                # Domain-Driven Modules (Processing Layer)
│   │   ├── auth/ 
│   │   ├── patient/
│   │   ├── audio/
│   │   ├── ai_service/
│   │   ├── billing/
│   │   ├── claim/
│   │   └── integration/        # EMR Adapter Implementations
│   ├── shared/                 # Cross-Module Resources
│   │   ├── models/             # Shared DB Mixins
│   │   ├── schemas/            # Generic Pydantic models (Pagination, Error)
│   │   └── utils/              # Global Utilities
│   │       ├── hipaa_logger.py # HIPAA-compliant JSON logging
│   │       ├── encryptor.py    # AES-256 Utility
│   │       └── date_helpers.py # TZ-aware time logic
│   └── ai_layer/               # AI Infrastructure (Local Inference)
│       ├── models/             # Model loading scripts
│       ├── rag/                # Vector store & RAG pipelines
│       └── inference/          # Local Whisper/LLM runners
├── scripts/                    # Operational Scripts (Data Migration, ETL)
├── tests/                      # Pytest Suite
├── alembic.ini                 # Migration config
├── docker-compose.yml          # Local Dev Orchestration
├── requirements.txt            # Dependency list
└── README.md
```

---

## 2. Granular Module Breakdown

Every domain module (`app/modules/<module>/`) follows this structure:

### `models.py`
Defines SQLAlchemy ORM models.
- *Example (Claim):* `Claim`, `ClaimHistory`, `AuditLog`.

### `schemas.py`
Defines Pydantic models for request validation and response serialization.
- *Example (Patient):* `PatientCreate`, `PatientPublic`, `PatientSearch`.

### `services/`
Contains the business logic decoupled from the API layer.
- `logic.py`: Primary business rules.
- `validators.py`: Domain-specific validation logic.

### `routers/`
FastAPI route definitions.
- `endpoints.py`: HTTP methods (GET, POST, etc.) and payload handling.

### `tasks/`
Celery background tasks.
- `worker.py`: Async task definitions for the specific module.

---

## 3. Specialized Layouts

### **Migrations (`app/database/migrations/`)**
- `versions/`: Auto-generated migration files reflecting schema changes.
- `env.py`: Connects Alembic to the FastAPI application metadata.

### **Utilities (`app/shared/utils/`)**
- `hipaa_logger.py`: Custom logging to ensure PHI isn't leaked in logs while satisfying audit trail requirements.
- `encryptor.py`: Standardized AES-256 GCM logic for encrypting audio files at rest.
- `emr_client.py`: Base HTTP client session for integration adapters.

### **AI Layer (`app/ai_layer/`)**
- `inference/whisper_runner.py`: Logic to feed audio blobs to the local Whisper engine.
- `rag/vector_indexer.py`: Logic to ingest PDF manuals/cheat-sheets into `pgvector`.

---

## 4. Key Implementation Files

- **`app/main.py`**: Initializes FastAPI, adds CORS, mounts `v1` router, and sets up startup/shutdown events (DB connection, Redis init).
- **`app/core/config.py`**: Uses `pydantic-settings` to load `.env` variables for Database URL, Redis URL, JWT Secret, and AI model paths.
- **`requirements.txt`**:
    - `fastapi`, `uvicorn`, `sqlalchemy[asyncio]`, `asyncpg`
    - `pydantic[email]`, `pydantic-settings`
    - `alembic`, `celery`, `redis`
    - `cryptography`, `python-jose[cryptography]`
    - `pgv-sdk` (for vector search)