# merginmaps/server architecture

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

- Interactive diagram: https://gitdiagram.com/merginmaps/server
- Repository: https://github.com/merginmaps/server

## Overview

1. This repository is a full-stack Mergin Maps server bundle: a Python backend, a Vue/TypeScript web client, and Docker-based deployment definitions. The architecture is centered on geospatial project storage, synchronization, user/project management, and admin operations.

2. The backend lives under `server/` and is split into domain modules. The main runtime is a Python web service started through a WSGI entrypoint, with background processing handled separately by Celery. Database schema changes are managed with Alembic migrations in `server/migrations/`.

3. The core backend subsystem is `server/mergin/sync/`. This is the project storage and synchronization domain: it exposes public and private APIs, contains project/file models and permissions, handles file uploads/downloads, version history, workspace logic, and project-specific handlers. The presence of `public_api*.yaml` and `private_api.yaml` shows the service is API-driven and organized around generated or contract-backed endpoints.

4. Authentication and account management are isolated in `server/mergin/auth/`. That module owns login/session or bearer-token handling, user forms/models/schemas, and related background tasks such as emails or account workflows. The admin and user-facing flows both depend on this boundary, but the sync domain is separate from identity concerns.

5. Usage analytics and operational reporting are in `server/mergin/stats/`. This is a distinct subsystem from core sync, indicating the platform records system/project statistics and exposes them through its own API and task processing.

6. Asynchronous work is handled by Celery (`server/mergin/celery.py` and module-specific `tasks.py`). Background jobs likely cover expensive sync processing, email delivery, statistics collection, and maintenance operations. This is an important architecture boundary because request/response API calls are not the only execution path.

7. Persistence is split between the relational database and project files on disk. The migrations indicate a long-lived schema with project membership, file history, upload concurrency, access requests, and versioning tables. The storage layer under `server/mergin/sync/storages/` currently includes disk-backed storage, so the system’s file content is managed separately from metadata in the database.

8. The backend is also instrumented for telemetry in `server/mergin/otel/`. This is wired for OpenTelemetry rather than being an external add-on, and the deployment folder includes Prometheus, Loki, Tempo, Alloy, and Grafana configs. In other words, observability is part of the system architecture, not an afterthought.

9. The web client is a monorepo under `web-app/` with three main packages: `app`, `admin-app`, and `lib`. `lib` is the shared product library containing reusable UI components, themes, common utilities, and domain modules; `app` is the main user-facing SPA; `admin-app` is the separate admin SPA. This split is a major architectural boundary in the frontend.

10. Frontend logic is organized into feature modules rather than page-only components. In `web-app/packages/lib/src/modules/` you can see dedicated modules for app shell, dashboard, dialog, form, instance status, layout, notification, project, and user flows. The user and project modules expose their own APIs, stores, routes, views, and components, which mirrors the server’s domain separation.

11. The public-facing app focuses on project collaboration and account workflows: project listing, project detail, collaborators, settings, profile, and login. The admin app and admin library focus on platform administration such as accounts, projects, reports, server configuration, and update checks. This indicates two distinct UX surfaces backed by different server endpoints and permission sets.

12. Deployment is containerized and split by audience and edition. `deployment/community/` provides the standard community stack, while `deployment/enterprise/` adds SSO-related components and configuration. `deployment/common/` contains shared entrypoint, Nginx, SSL proxy, and telemetry assets, showing that reverse proxying, TLS termination, and observability are first-class deployment concerns.

13. The enterprise deployment introduces an additional authentication boundary through SSO services and proxy configuration. That means auth is not just application-level; in enterprise mode there is an external identity integration layer in front of the backend/admin flows.

14. Overall data flow is: browser clients talk to the appropriate web app, which calls the backend APIs; the backend authenticates the request, enforces permissions, reads/writes project metadata in the database, stores project files in disk-backed storage, and queues slower tasks to Celery. Admin and telemetry concerns are separated from the main sync path, which keeps the architecture modular and easier to diagram accurately.

Main entry points: [`server/mergin/app.py`](https://github.com/merginmaps/server/blob/master/server/mergin/app.py) (Core app), [`web-app/packages/lib/src/main.ts`](https://github.com/merginmaps/server/blob/master/web-app/packages/lib/src/main.ts) (Shared lib), [`deployment/common`](https://github.com/merginmaps/server/tree/master/deployment/common) (Common ops), [`server/mergin/sync`](https://github.com/merginmaps/server/tree/master/server/mergin/sync) (Sync API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_server_app["Web app<br/>python entrypoint<br/>[application.py]"]
  node_server_core["Core app<br/>backend shell<br/>[app.py]"]
  node_sync_api[("Sync API<br/>project sync")]
  node_sync_storage["Disk store<br/>file storage<br/>[disk.py]"]
  node_sync_tasks["Sync jobs<br/>celery tasks<br/>[tasks.py]"]
  node_auth_domain["Auth<br/>identity"]
  node_stats_domain["Stats<br/>analytics"]
  node_celery_runtime(("Celery<br/>async runtime<br/>[celery.py]"))
  node_otel_instrument["Telemetry<br/>observability"]
  node_migrations["Migrations<br/>schema history"]
end

subgraph group_frontend["Frontend"]
  node_web_app["User app<br/>vue spa<br/>[main.ts]"]
  node_admin_app["Admin app<br/>vue spa<br/>[main.ts]"]
  node_shared_lib["Shared lib<br/>frontend platform<br/>[main.ts]"]
  node_frontend_project["Project UI<br/>feature module"]
  node_frontend_user["User UI<br/>feature module"]
  node_frontend_admin["Admin UI<br/>feature module"]
  node_frontend_layout["Shell UI<br/>feature module"]
end

subgraph group_deployment["Deployment"]
  node_deploy_common["Common ops<br/>docker assets"]
  node_deploy_community["Community stack<br/>compose bundle"]
  node_deploy_enterprise["Enterprise stack<br/>compose bundle"]
end

node_server_app -->|"boots"| node_server_core
node_server_core -->|"hosts"| node_sync_api
node_server_core -->|"uses"| node_auth_domain
node_server_core -->|"uses"| node_stats_domain
node_server_core -->|"instruments"| node_otel_instrument
node_sync_api -->|"stores"| node_sync_storage
node_sync_api -->|"queues"| node_sync_tasks
node_sync_api -->|"persists"| node_migrations
node_auth_domain -->|"runs on"| node_celery_runtime
node_stats_domain -->|"runs on"| node_celery_runtime
node_sync_tasks -->|"executes on"| node_celery_runtime
node_web_app -->|"shares"| node_shared_lib
node_admin_app -->|"shares"| node_shared_lib
node_shared_lib -->|"contains"| node_frontend_project
node_shared_lib -->|"contains"| node_frontend_user
node_shared_lib -->|"contains"| node_frontend_admin
node_shared_lib -->|"contains"| node_frontend_layout
node_deploy_community -->|"extends"| node_deploy_common
node_deploy_enterprise -->|"extends"| node_deploy_common
node_deploy_enterprise -->|"integrates"| node_auth_domain
node_web_app -->|"calls"| node_server_core
node_admin_app -->|"calls"| node_server_core
node_deploy_common -->|"hosts"| node_server_app
node_deploy_common -->|"hosts"| node_web_app
node_deploy_common -->|"hosts"| node_admin_app

click node_server_app "https://github.com/merginmaps/server/blob/master/server/application.py"
click node_server_core "https://github.com/merginmaps/server/blob/master/server/mergin/app.py"
click node_sync_api "https://github.com/merginmaps/server/tree/master/server/mergin/sync"
click node_sync_storage "https://github.com/merginmaps/server/blob/master/server/mergin/sync/storages/disk.py"
click node_sync_tasks "https://github.com/merginmaps/server/blob/master/server/mergin/sync/tasks.py"
click node_auth_domain "https://github.com/merginmaps/server/tree/master/server/mergin/auth"
click node_stats_domain "https://github.com/merginmaps/server/tree/master/server/mergin/stats"
click node_celery_runtime "https://github.com/merginmaps/server/blob/master/server/mergin/celery.py"
click node_otel_instrument "https://github.com/merginmaps/server/tree/master/server/mergin/otel"
click node_migrations "https://github.com/merginmaps/server/tree/master/server/migrations"
click node_web_app "https://github.com/merginmaps/server/blob/master/web-app/packages/app/src/main.ts"
click node_admin_app "https://github.com/merginmaps/server/blob/master/web-app/packages/admin-app/src/main.ts"
click node_shared_lib "https://github.com/merginmaps/server/blob/master/web-app/packages/lib/src/main.ts"
click node_frontend_project "https://github.com/merginmaps/server/tree/master/web-app/packages/lib/src/modules/project"
click node_frontend_user "https://github.com/merginmaps/server/tree/master/web-app/packages/lib/src/modules/user"
click node_frontend_admin "https://github.com/merginmaps/server/tree/master/web-app/packages/admin-lib/src/modules/admin"
click node_frontend_layout "https://github.com/merginmaps/server/tree/master/web-app/packages/lib/src/modules/layout"
click node_deploy_common "https://github.com/merginmaps/server/tree/master/deployment/common"
click node_deploy_community "https://github.com/merginmaps/server/tree/master/deployment/community"
click node_deploy_enterprise "https://github.com/merginmaps/server/tree/master/deployment/enterprise"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_app,node_server_core,node_sync_api,node_sync_storage,node_sync_tasks,node_auth_domain,node_stats_domain,node_celery_runtime,node_otel_instrument,node_migrations toneBlue
class node_web_app,node_admin_app,node_shared_lib,node_frontend_project,node_frontend_user,node_frontend_admin,node_frontend_layout toneAmber
class node_deploy_common,node_deploy_community,node_deploy_enterprise toneMint
```

## Components

### Backend

Python web service, domain modules, async jobs, and migrations.

- [Web app](https://github.com/merginmaps/server/blob/master/server/application.py): python entrypoint · WSGI entrypoint and main application bootstrap for the Python backend. · `server/application.py`
- [Core app](https://github.com/merginmaps/server/blob/master/server/mergin/app.py): backend shell · Main backend package wiring config, commands, controller, and app setup. · `server/mergin/app.py`
- [Sync API](https://github.com/merginmaps/server/tree/master/server/mergin/sync): project sync · Core project storage and synchronization domain with public and private APIs, permissions, files, versions, and workspace logic. · `server/mergin/sync`
- [Disk store](https://github.com/merginmaps/server/blob/master/server/mergin/sync/storages/disk.py): file storage · Storage abstraction and disk-backed project content persistence. · `server/mergin/sync/storages/disk.py`
- [Sync jobs](https://github.com/merginmaps/server/blob/master/server/mergin/sync/tasks.py): celery tasks · Background work for sync-related processing and maintenance. · `server/mergin/sync/tasks.py`
- [Auth](https://github.com/merginmaps/server/tree/master/server/mergin/auth): identity · Authentication and account management boundary including bearer/session handling, forms, schemas, controllers, and account tasks. · `server/mergin/auth`
- [Stats](https://github.com/merginmaps/server/tree/master/server/mergin/stats): analytics · Usage analytics and operational reporting subsystem with its own API and tasks. · `server/mergin/stats`
- [Celery](https://github.com/merginmaps/server/blob/master/server/mergin/celery.py): async runtime · Shared background worker runtime used by backend task modules. · `server/mergin/celery.py`
- [Telemetry](https://github.com/merginmaps/server/tree/master/server/mergin/otel): observability · OpenTelemetry integration for backend instrumentation. · `server/mergin/otel`
- [Migrations](https://github.com/merginmaps/server/tree/master/server/migrations): schema history · Alembic database migrations for project, membership, upload, and versioning tables. · `server/migrations`

### Frontend

Vue/TypeScript applications and shared UI library.

- [User app](https://github.com/merginmaps/server/blob/master/web-app/packages/app/src/main.ts): vue spa · Main user-facing Vue/TypeScript single-page app for collaboration and account workflows. · `web-app/packages/app/src/main.ts`
- [Admin app](https://github.com/merginmaps/server/blob/master/web-app/packages/admin-app/src/main.ts): vue spa · Separate admin-facing Vue/TypeScript application. · `web-app/packages/admin-app/src/main.ts`
- [Shared lib](https://github.com/merginmaps/server/blob/master/web-app/packages/lib/src/main.ts): frontend platform · Reusable frontend library with common UI, modules, APIs, stores, routes, and theme assets. · `web-app/packages/lib/src/main.ts`
- [Project UI](https://github.com/merginmaps/server/tree/master/web-app/packages/lib/src/modules/project): feature module · Shared project feature module for listing, collaborators, files, versions, uploads, and sharing. · `web-app/packages/lib/src/modules/project`
- [User UI](https://github.com/merginmaps/server/tree/master/web-app/packages/lib/src/modules/user): feature module · Shared user feature module for login, profile, password, email verification, and account actions. · `web-app/packages/lib/src/modules/user`
- [Admin UI](https://github.com/merginmaps/server/tree/master/web-app/packages/admin-lib/src/modules/admin): feature module · Admin feature module for accounts, projects, reports, server settings, and update checks. · `web-app/packages/admin-lib/src/modules/admin`
- [Shell UI](https://github.com/merginmaps/server/tree/master/web-app/packages/lib/src/modules/layout): feature module · Shared layout, dashboard, dialog, notification, and instance modules that frame the apps. · `web-app/packages/lib/src/modules/layout`

### Deployment

Community and enterprise container stacks plus shared ops assets.

- [Common ops](https://github.com/merginmaps/server/tree/master/deployment/common): docker assets · Shared container entrypoint, Nginx, SSL proxy, and telemetry assets. · `deployment/common`
- [Community stack](https://github.com/merginmaps/server/tree/master/deployment/community): compose bundle · Community deployment composition and environment templates. · `deployment/community`
- [Enterprise stack](https://github.com/merginmaps/server/tree/master/deployment/enterprise): compose bundle · Enterprise deployment with SSO-related services and proxy configuration. · `deployment/enterprise`

## Connections

- Web app → Core app: boots · WSGI entrypoint initializes the backend app.
- Core app → Sync API: hosts · Main backend exposes the sync domain APIs.
- Core app → Auth: uses · Backend routes authentication and account flows through auth.
- Core app → Stats: uses · Backend exposes operational stats through a separate domain.
- Core app → Telemetry: instruments · App startup wires telemetry instrumentation.
- Sync API → Disk store: stores · Project files are persisted through storage abstractions.
- Sync API → Sync jobs: queues · Sync operations offload slower work to background jobs.
- Sync API → Migrations: persists · Sync metadata relies on the evolving relational schema.
- Auth → Celery: runs on · Auth-related workflows can execute asynchronously.
- Stats → Celery: runs on · Statistics collection and reporting use background workers.
- Sync jobs → Celery: executes on · Sync job module is consumed by Celery workers.
- User app → Shared lib: shares · Main SPA consumes the shared frontend library.
- Admin app → Shared lib: shares · Admin SPA consumes the shared frontend library.
- Shared lib → Project UI: contains · Project collaboration UI is a central shared feature.
- Shared lib → User UI: contains · User account flows live in a shared feature module.
- Shared lib → Admin UI: contains · Admin capabilities are organized as a dedicated module.
- Shared lib → Shell UI: contains · Shared shell and utility modules frame the apps.
- Community stack → Common ops: extends · Community stack reuses shared deployment assets.
- Enterprise stack → Common ops: extends · Enterprise stack reuses shared deployment assets.
- Enterprise stack → Auth: integrates · Enterprise deployment adds SSO integration in front of application auth.
- User app → Core app: calls · User SPA talks to backend APIs.
- Admin app → Core app: calls · Admin SPA talks to backend APIs.
- Common ops → Web app: hosts · Container and proxy assets serve the backend service.
- Common ops → User app: hosts · Shared reverse-proxy assets serve the user web app.
- Common ops → Admin app: hosts · Shared reverse-proxy assets serve the admin web app.