# dzd-ev-diabetes-research/dzdmedlog architecture

> Architecture diagram of the GitHub repository dzd-ev-diabetes-research/dzdmedlog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dzd-ev-diabetes-research/dzdmedlog
- Repository: https://github.com/dzd-ev-diabetes-research/dzdmedlog

## Overview

##### Project Type and Purpose
- DZDMedLog is a full-stack web application for logging medication histories of study participants.
- The backend is a Python service (FastAPI/Starlette style) with REST/OpenAPI endpoints, database migrations (Alembic), data models (SQLAlchemy), and a background worker process.
- The frontend is a Nuxt3/Vue3 single-page application (SPA) written in TypeScript, served to browsers.

##### File-Structure Analysis
- Top-level: Docker/CI config, Makefile, OpenAPI spec.
- MedLog/backend:
- medlogserver (app.py, main.py): API routes under `api/routes`, auth, config, logging.
- db layer: engine/session, CRUD base, migrations, domain tables (drug_data, event, intake, user, study, etc.).
- model layer: ORM model definitions matching tables and Pydantic/DTO factories.
- worker: background tasks (export, provisioning, token cleanup, ad hoc jobs).
- dev support: OIDC mock server, default_data.yaml, test suite.
- MedLog/frontend:

##### README Insights
- Emphasizes Dockerized deployment (demo mode, custom drug DB mount).
- Local source run: bun/npm for frontend, Python 3.11 + virtualenv for backend.
- Development scripts for server, client, OIDC mock.
- OpenAPI docs available at `/docs`.

a. Main Components
- User Browser (Web Client)
- Nuxt3 Frontend (served at port 3000 in dev, static + API proxy)
- Python Backend API (uvicorn/gunicorn running FastAPI)
- Relational Database (SQLite by default or external RDBMS)
- Background Worker (same codebase, separate process)
- OIDC Identity Provider (external or development mock)
- Drug Data Store (mounted filesystem directory with CSV/YAML)
- CI/CD & Docker Registry
b. Relationships & Data Flows
- Browser ↔ HTTP(S) ↔ Frontend (SPA)
- Frontend ↔ HTTP(S) ↔ Backend API (REST + JSON)
- Backend ↔ SQL ↔ Database
- Backend ↔ Reads/Writes ↔ Drug Data Files on disk
- Backend ↔ Message/Task Queue or Direct Invoke ↔ Worker
- Backend ↔ OIDC ↔ Identity Provider (token exchange, userinfo)
- CI Workflow ↔ Builds & Pushes ↔ Docker Hub
c. Architectural Patterns & Principles
- Layered architecture: Presentation (Frontend) → API Layer → Service/Model → Data Access → Persistence
- Clean separation: synchronous API vs asynchronous worker tasks
- Infrastructure as code: containerized services, scripts for env setup
- Security: OIDC-based authentication and authorization, JWT in API calls
- Progressive enhancement: static site generation (Nuxt generate) + dynamic hydration
d. Key Technologies
- Frontend: Nuxt3/Vue3, TypeScript, Pinia stores, bun/npm, Tailwind CSS
- Backend: Python 3.11, FastAPI/Starlette, SQLAlchemy, Alembic, Pydantic, Uvicorn
- Worker: custom task module under medlogserver.worker (no external queue)
- Authentication: OIDC (Keycloak or mock server)
- Database: SQLite (dev/demo) or any SQL-compliant DB
- Deployment: Docker, GitHub Actions CI

##### Detailed Guidance
- Drill down to Container Level: show each runtime container/process.
- Component with tech stacks (e.g., “Nuxt3 + TypeScript”, “FastAPI + SQLAlchemy”).
- Interaction patterns: REST endpoints, background jobs, migrations.
- Don’t overcrowd: focus on data flow paths that capture request handling, data persistence, and background tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["User Browser"]:::client
        Frontend["Nuxt3 Frontend"]:::client
        Browser -->|"loads SPA via HTTP/HTTPS"| Frontend
    end

    %% Frontend Components
    subgraph "Frontend Components"
        direction TB
        Config["nuxt.config.ts / app.config.ts"]:::client
        Pages["pages (SPA routes)"]:::client
        ComponentsFE["components"]:::client
        Stores["stores (Pinia)"]:::client
        Composables["composables"]:::client
        Plugins["plugins"]:::client
        Assets["assets & public"]:::client
    end
    Frontend --> Config
    Frontend --> Pages
    Frontend --> ComponentsFE
    Frontend --> Stores
    Frontend --> Composables
    Frontend --> Plugins
    Frontend --> Assets

    %% Server Layer
    subgraph "Server Layer"
        direction TB

        subgraph "Backend API"        
            direction TB
            APIEntry["app.py / main.py"]:::backend
            Routes["api/routes"]:::backend
            APIInfra["api/base, paginator, routers_map"]:::backend
            Auth["api/auth/security, utils"]:::backend
            ConfigLog["config.py, log.py"]:::backend
        end

        subgraph "Database Layer"
            direction TB
            DBEngine["_engine.py / _session.py / _init_db.py"]:::data
            CrudBase["_base_crud.py"]:::data
            DomainTables["ORM tables (*.py)"]:::data
            Migrations["alembic/ & alembic.ini"]:::data
        end

        subgraph "Models & DTOs"
            direction TB
            Models["model/*.py"]:::backend
            DrugModels["model/drug_data/*.py"]:::backend
        end

        subgraph "Background Worker"
            direction TB
            WorkerEntry["worker/worker.py"]:::backend
            Tasks["worker/tasks"]:::backend
            Dispatcher["worker/task.py"]:::backend
        end

        subgraph "Dev OIDC Mock"
            direction TB
            OIDCMock["oidc_provider_mock_server.py"]:::external
            TestUsers["testusers.yaml"]:::external
        end

        subgraph "Drug Data Store"
            direction TB
            ProvisionData["provisioning_data"]:::data
            DefaultData["default_data.yaml"]:::data
        end

        %% API flows
        Frontend -->|"REST/JSON"| APIEntry
        APIEntry --> Routes
        APIEntry --> APIInfra
        APIEntry --> Auth
        APIEntry --> ConfigLog
        APIEntry --> Models
        APIEntry --> DrugModels

        %% DB flows
        APIEntry -->|"SQL"| DBEngine
        DBEngine --> CrudBase
        DBEngine --> DomainTables
        DBEngine --> Migrations

        %% Worker flows
        APIEntry -->|"Task dispatch"| Dispatcher
        Dispatcher --> Tasks
        Dispatcher --> WorkerEntry

        %% OIDC flows
        APIEntry -->|"OIDC token exchange"| OIDCMock

        %% Drug Data flows
        APIEntry -->|"File I/O"| ProvisionData
        APIEntry --> DefaultData
    end

    %% External / Infrastructure
    subgraph "External Dependencies"
        direction TB
        CI["CI/CD & Docker Registry"]:::external
        OIDCReal["OIDC Provider (Prod)"]:::external
    end
    CI -->|"pushes images"| APIEntry
    CI -->|"pushes images"| Frontend
    APIEntry -->|"token exchange (prod)"| OIDCReal

    %% Legend
    subgraph "Legend"
        direction TB
        A1["Blue = Client/UI"]:::client
        A2["Green = Backend/API"]:::backend
        A3["Yellow = Data Persistence"]:::data
        A4["Gray = External"]:::external
    end

    %% Click Events
    click Browser "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend"
    click Frontend "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend"
    click Config "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/frontend/nuxt.config.ts"
    click Pages "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend/pages"
    click ComponentsFE "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend/components"
    click Stores "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend/stores"
    click Composables "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend/composables"
    click Plugins "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend/plugins"
    click Assets "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/frontend/assets"
    click APIEntry "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/app.py"
    click Routes "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/backend/medlogserver/api/routes"
    click APIInfra "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/api/base.py"
    click Auth "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/api/auth/security.py"
    click ConfigLog "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/config.py"
    click DBEngine "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/db/_engine.py"
    click CrudBase "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/db/_base_crud.py"
    click DomainTables "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/db/event.py"
    click Migrations "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/backend/medlogserver/alembic/"
    click Models "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/backend/medlogserver/model/"
    click DrugModels "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/backend/medlogserver/model/drug_data/"
    click WorkerEntry "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/worker/worker.py"
    click Tasks "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/backend/medlogserver/worker/tasks/"
    click Dispatcher "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/worker/task.py"
    click OIDCMock "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/_dev/oidc_provider_mock_server.py"
    click ProvisionData "https://github.com/dzd-ev-diabetes-research/dzdmedlog/tree/dev/MedLog/backend/provisioning_data/"
    click DefaultData "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/MedLog/backend/medlogserver/default_data.yaml"
    click CI "https://github.com/dzd-ev-diabetes-research/dzdmedlog/blob/dev/.github/workflows/build-push-server.yaml"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
