Skip to content

Development

Everything you need to work on the DiagramaHub codebase: how it is built, how to run the environment, how to test and how to ship a release.

  • Architecture

    Services, data flow, diagram rendering and the AI chat flow.

    See architecture

  • Backend

    FastAPI + MongoDB: the 12 modules, the layered pattern and configuration.

    See backend

  • Frontend

    React 19 + Vite: routes, contexts, API layer, i18n and design system.

    See frontend

  • REST API

    Conventions, authentication, errors and the endpoint map.

    See API

  • Testing

    pytest in Docker, coverage floor, Vitest and the AI benchmark.

    See testing

  • Extending DiagramaHub

    New modules, AI providers, pages and UI text.

    See the guide

  • Versioning and releases

    SemVer, release/<V> branches and the version check.

    See versioning

  • Contributing

    PR flow, code style and how to report issues.

    See how to contribute

Running the development environment

Everything runs in Docker Compose: you don't need Python or Node on your machine to use the app (you do need Node to run pnpm or Vitest outside the container).

git clone https://github.com/diagramahub/diagramahub.git
cd diagramahub

# Backend variables (JWT_SECRET at minimum)
cp backend/.env.example backend/.env

# The root docker-compose.yml is a symlink to the deployment mode
ln -sf deploy/local-full/docker-compose.yml docker-compose.yml

docker-compose up -d --build
Service Container URL / port In development
Frontend diagramahub-frontend http://localhost:5173 Vite dev server with HMR (development stage of the Dockerfile)
Backend diagramahub-backend http://localhost:5172 Uvicorn with hot reload
Swagger / ReDoc — http://localhost:5172/docs · /redoc Outside production only
Kroki diagramahub-kroki internal Renders PlantUML, D2 and DBML
MongoDB diagramahub-mongodb 27017 Persistent volume (local-full mode)

First run

The first time you open the frontend, the setup wizard (/setup) creates the administrator account. See Installation.

Common commands:

docker-compose logs -f backend          # backend logs
docker exec -it diagramahub-backend bash
docker exec -it diagramahub-mongodb mongosh
docker-compose build frontend --no-cache

Frontend package manager

The frontend uses pnpm (packageManager: pnpm@9.15.9 in frontend/package.json, lockfile pnpm-lock.yaml). Scripts: pnpm dev, pnpm build, pnpm lint, pnpm test.