How josephneumann/cruxmd works
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”)