aibilly_backend_code/project_structure_detailed.md

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.