How dzd-ev-diabetes-research/dzdmedlog works
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.