Project Structure

medical/
├── backend/                  # FastAPI application
│   ├── app/
│   │   ├── api/             # Route handlers (REST endpoints)
│   │   ├── application/     # Business logic (application services)
│   │   ├── domain/          # Domain entities, value objects, exceptions
│   │   ├── infrastructure/  # SQLAlchemy models, repositories, storage, scheduler
│   │   ├── schemas/         # Pydantic v2 request/response schemas
│   │   ├── auth/            # JWT token service
│   │   ├── config.py        # Pydantic settings from .env (incl. DB pool config)
│   │   └── main.py          # FastAPI app entry point
│   ├── alembic/             # Database migrations (10 versions)
│   ├── scripts/             # create_user.py, backfill_body_regions.py
│   ├── tests/               # pytest suite (18 files, 135 tests)
│   └── documents/           # Uploaded medical files
├── frontend/                 # Vue.js 3 SPA
│   ├── src/
│   │   ├── views/           # Page components (18 views)
│   │   ├── components/      # Reusable components
│   │   ├── stores/          # Pinia state management (9 stores)
│   │   ├── composables/     # useTheme, usePush, useOnlineStatus, useUrlFilters
│   │   ├── api/             # Axios client with JWT interceptor
│   │   ├── types/           # TypeScript type definitions
│   │   ├── utils/           # Date formatting, chart setup
│   │   └── router/          # Vue Router with auth guards
│   └── public/
│       ├── icons/           # PWA icons
│       └── sw-push.js       # Push notification service worker
├── docker-compose.yml
├── Makefile                  # Dev commands
└── .github/workflows/ci.yml # CI pipeline

Backend Architecture

The backend follows a layered / hexagonal architecture pattern with clear separation of concerns.

Request Flow

flowchart LR
    A["HTTP Request"] --> B["API Route"]
    B --> C["Dependency Injection"]
    C --> D["Application Service"]
    D --> E["Repository"]
    E --> F["Database"]

Layers

Exception Handling

Soft Deletes vs Hard Deletes

• Soft delete (sets deleted_at): Visit, Treatment, Vaccination, LabResult
• Hard delete: HealthMetric, MetricType, BiomarkerReference, References (Position, Procedure, Clinic, City), NotificationDismissal, PushSubscription, PushSentLog, User

Frontend Architecture

Composition API + Script Setup

All components use Vue 3 <script setup lang="ts"> with the Composition API.

State Management (Pinia)