# josephneumann/cruxmd architecture

> Architecture diagram of the GitHub repository josephneumann/cruxmd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josephneumann/cruxmd
- Repository: https://github.com/josephneumann/cruxmd

## Overview

##### Project type and purpose
- This is a full-stack monorepo containing:
- A Python FastAPI backend service
- A React/Next.js frontend application
- A shared OpenAPI schema and generated TypeScript client
- Infrastructure (Docker Compose, GitHub Actions, Vercel configs)
- Purpose: provide a high-signal clinical “copilot” with user auth, patient pages, AI-assisted features, and email workflows.

##### File structure
- Top-level directories:
- fastapi_backend – Python backend (app, Alembic migrations, tests, commands, Dockerfile)
- nextjs-frontend – TypeScript/Next.js frontend (app routes, components, openapi-client, tests)
- local-shared-data/openapi.json – latest OpenAPI schema
- CI/CD configs in .github/workflows, Docker Compose file, Makefile
- Key patterns:
- Monorepo split (backend vs frontend)
- Automated codegen/watchers update OpenAPI schema and regenerate client
- Docker Compose for local dev orchestration
- Vercel config for separate front & back deployments

##### README for additional insights
- Tech stack and workflows: FastAPI, SQLAlchemy, PostgreSQL, Pydantic, Next.js, Zod, Shadcn/ui
- Watchers: Watchdog (backend), Chokidar (frontend) for hot-reload + codegen
- GitHub Actions: CI for lint/test, CD for Vercel deployments (frontend & backend)

##### Diagramming the system
a. Main components
- Next.js Frontend
- OpenAPI-TS Generated Client
- FastAPI Backend
- PostgreSQL Database
- Mail service (MailHog for dev, external SMTP for prod)
- Codegen Watchers (Watchdog, Chokidar)
- CI/CD Pipelines (GitHub Actions)
- Docker Compose orchestration (nginx/db/backend/frontend containers)
- Vercel Hosting (Frontend & Backend)

b. Relationships and data flows
- Frontend → Backend: HTTP(S) REST calls via generated OpenAPI client
- Backend → Database: ORM (SQLAlchemy) queries / migrations (Alembic)
- Backend → Email Service: SMTP calls for password reset, verification
- Watchdog (backend folder) on code/schema changes → regenerate openapi.json → Chokidar (frontend) watches schema → regenerate TS client
- Developers → Docker Compose: spin up db + mailhog + services locally
- GitHub Actions → run tests, build images, deploy to Vercel

c. Architectural patterns & principles
- Monolithic services with clear separation of concerns (API layer, business logic, data layer)
- API-first design (OpenAPI schema as source of truth)
- Type-safe end-to-end contracts (Pydantic + Zod + generated client)
- Dev/prod parity (Docker Compose vs Vercel)
- CI/CD with immutable deployments

d. Key technologies/frameworks
- FastAPI, SQLAlchemy, Alembic, uv, pytest
- Next.js (app router), Shadcn/ui, pnpm, TypeScript, Zod
- @hey-api/openapi-ts (client codegen)
- Watchdog & Chokidar for hot-reload & codegen
- Docker, Docker Compose, Vercel

- Clear, descriptive labels (e.g., “FastAPI API”, “Next.js App”, “PostgreSQL DB”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Development Environment
    subgraph "Local Development" 
        direction TB
        DC["Docker Compose"]:::infra
        DC -->|orchestrates| BE_DEV["FastAPI Service (Dev)"]:::api
        DC -->|orchestrates| FE_DEV["Next.js App (Dev)"]:::ui
        DC -->|orchestrates| DB_DEV["PostgreSQL DB"]:::data
        DC -->|orchestrates| MH["MailHog (SMTP)"]:::infra
    end

    %% Production Environment
    subgraph "Production (Vercel)" 
        direction TB
        VERCEL_FE["Frontend Hosting"]:::cloud
        VERCEL_BE["Backend Hosting"]:::cloud
        SMTP["External SMTP"]:::cloud
    end

    %% CI/CD
    subgraph "CI/CD Pipelines" 
        direction TB
        GH_CI["GitHub Actions CI"]:::infra
        GH_CD_FE["Frontend Deploy"]:::infra
        GH_CD_BE["Backend Deploy"]:::infra
        GH_CI -->|runs tests| BE_DEV
        GH_CI -->|runs tests| FE_DEV
        GH_CD_FE -->|"deploys"| VERCEL_FE
        GH_CD_BE -->|"deploys"| VERCEL_BE
    end

    %% Codegen Feedback Loop
    subgraph "Codegen Loop" 
        direction TB
        WD["Watchdog (Backend)"]:::infra
        OAS["OpenAPI Schema"]:::data
        CK["Chokidar (Frontend)"]:::infra
        TS_CLIENT["Generated TS Client"]:::api
        WD -->|updates| OAS
        OAS -->|triggers| CK
        CK -->|regenerates| TS_CLIENT
    end

    %% Main App Components
    FE_DEV -->|calls REST API| TS_CLIENT
    TS_CLIENT -->|requests| BE_DEV
    BE_DEV -->|queries| DB_DEV
    BE_DEV -->|sends SMTP| MH
    BE_DEV -->|sends SMTP| SMTP
    FE_DEV -->|UI render| components

    %% Production Flows
    VERCEL_FE -->|calls REST API| VERCEL_BE
    VERCEL_BE -->|queries| DB_DEV
    VERCEL_BE -->|sends SMTP| SMTP

    %% File-level Click Events
    click BE_DEV "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/app/main.py"
    click API_ROUTES "https://github.com/josephneumann/cruxmd/tree/main/fastapi_backend/app/routes/"
    click MODELS "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/app/models.py"
    click SCHEMAS "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/app/schemas.py"
    click DB_SETUP "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/app/database.py"
    click ALEMBIC "https://github.com/josephneumann/cruxmd/tree/main/fastapi_backend/alembic_migrations/"
    click EMAIL_LOGIC "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/app/email.py"
    click EMAIL_TEMPLATES "https://github.com/josephneumann/cruxmd/tree/main/fastapi_backend/app/email_templates/"
    click CMD_OAS "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/commands/generate_openapi_schema.py"
    click WD "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/watcher.py"
    click OAS "https://github.com/josephneumann/cruxmd/blob/main/local-shared-data/openapi.json"
    click TS_CLIENT "https://github.com/josephneumann/cruxmd/blob/main/nextjs-frontend/app/openapi-client/sdk.gen.ts"
    click TS_CLIENT "https://github.com/josephneumann/cruxmd/blob/main/nextjs-frontend/app/openapi-client/types.gen.ts"
    click TS_CLIENT "https://github.com/josephneumann/cruxmd/blob/main/nextjs-frontend/app/openapi-client/index.ts"
    click FE_DEV "https://github.com/josephneumann/cruxmd/tree/main/nextjs-frontend/app/"
    click components "https://github.com/josephneumann/cruxmd/tree/main/nextjs-frontend/components/"
    click FE_WATCHER "https://github.com/josephneumann/cruxmd/blob/main/nextjs-frontend/watcher.js"
    click DC "https://github.com/josephneumann/cruxmd/blob/main/docker-compose.yml"
    click GH_CI "https://github.com/josephneumann/cruxmd/blob/main/.github/workflows/ci.yml"
    click GH_CD_BE "https://github.com/josephneumann/cruxmd/blob/main/.github/workflows/prod-backend-deploy.yml"
    click GH_CD_FE "https://github.com/josephneumann/cruxmd/blob/main/.github/workflows/prod-frontend-deploy.yml"
    click VERCEL_BE "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/vercel.json"
    click VERCEL_BE "https://github.com/josephneumann/cruxmd/blob/main/fastapi_backend/vercel.prod.json"
    click VERCEL_FE "https://github.com/josephneumann/cruxmd/blob/main/nextjs-frontend/vercel.json"
    click MAKEFILE "https://github.com/josephneumann/cruxmd/tree/main/Makefile"
    click SCRIPTS "https://github.com/josephneumann/cruxmd/tree/main/scripts/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef api fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#fff3cd,stroke:#856404,color:#856404;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cloud fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
