# Detailed File-Level Project Structure: IamBilly Backend

This document provides an exhaustive file-level breakdown of the IamBilly backend, adhering to the monolithic modular pattern and the stack requirements (FastAPI, PostgreSQL, Redis, AI Layer).

---

## 1. Global Core Structure (`app/`)

### `app/core/`
- `config.py`: Centralized environment variable management (Pydantic Settings).
- `security.py`: JWT token generation, password hashing, and OAuth2 scopes.
- `encryption.py`: AES-256 logic for at-rest storage of audio and PHI.
- `logging.py`: HIPAA-compliant JSON logging with audit trail metadata.
- `exceptions.py`: Custom HTTP exception handlers for global error responses.

### `app/api/`
- `v1/api.py`: Main router that includes all module-level routers.
- `dependencies.py`: Global FastAPI dependencies (e.g., `get_current_active_user`).

### `app/database/`
- `base.py`: Import all SQLAlchemy models here for Alembic detection.
- `session.py`: Database engine and async session factory setup.
- `crud.py`: Common CRUD operations for shared entities.

---

## 2. Domain Modules (`app/modules/`)

Every module below follows this structure: `<module>/[models.py, schemas.py, service.py, router.py, tasks.py]`.

### `modules/auth/`
- `models.py`: `User`, `Role`, `Permission` tables.
- `schemas.py`: Login, Token, and User management schemas.
- `service.py`: Authentication logic, role verification.
- `router.py`: `/login`, `/refresh`, `/me` endpoints.

### `modules/patient/`
- `models.py`: `Patient`, `PatientEMRMap`.
- `schemas.py`: Patient search results and metadata.
- `service.py`: Real-time Lookup logic (caching EMR results).
- `router.py`: `/patients/search`, `/patients/{id}`.

### `modules/audio/`
- `models.py`: `Recording`, `AudioSession`.
- `schemas.py`: Upload validation and status updates.
- `service.py`: Secure file handling, metadata extraction.
- `router.py`: `/audio/upload`, `/audio/{id}/status`.
- `tasks.py`: Background task to move files to encrypted object storage.

### `modules/ai_service/`
- `service.py`: Orchestrator for the "Voice-to-Claim" pipeline.
- `extraction.py`: NLP logic for entity extraction (Diagnosis, Procedure, Laterality).
- `transcription.py`: Integration with Whisper STT.
- `tasks.py`: Celery worker for long-running STT/LLM inference.

### `modules/billing/`
- `models.py`: `PayerRule`, `NCCIEdit`, `ModifierMap`.
- `service.py`: Rules engine logic, optimization strategies for 10-20 spine procedures.
- `rag_service.py`: Logic to query the `ai_layer` vector store for scrubbing.
- `router.py`: `/billing/payer-rules`.

### `modules/claim/`
- `models.py`: `Claim` (State Machine), `ClaimRevision`, `AuditTrail`.
- `schemas.py`: Full CMS-1500 JSON representation.
- `service.py`: Lifecycle management (Draft -> Human Review -> Exported).
- `router.py`: `/claims/queue`, `/claims/{id}/approve`, `/claims/{id}/reject`.

---

## 3. Infrastructure & Integration Layer

### `app/ai_layer/`
- `models/`: Loader scripts for Llama/Mistral/Qwen models.
- `rag/`: Vector DB initialization (pgvector), indexing policy docs/manuals.
- `inference/`: `whisper_service.py` (STT extraction) and `llm_service.py` (Entity Extraction).

### `app/integration/`
- `base_adapter.py`: Abstract base class for EMR integrations.
- `epic_fhir.py`: Epic R4 FHIR client (Patient, Encounter, DocRef resources).
- `athena_api.py`: Custom client for Athena Centricity.
- `curemd_api.py`: CureMD REST client.

---

## 4. Root Config Files
- `main.py`: App initialization, Middleware (CORS/HIPAA logging), and API Mounting.
- `celery_app.py`: Celery configuration for async tasks.
- `alembic.ini`: Database migration config.
- `docker-compose.yml`: Definition for `api`, `worker`, `db`, `redis`.
- `requirements.txt`: To include: `fastapi`, `sqlalchemy[asyncio]`, `pgv-sdk`, `pydantic-settings`, `celery`, `redis`, `python-multipart`, `cryptography`.