aibilly_backend_code/project_structure.md

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

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)