How merginmaps/server works
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: app.py Core app · main.ts Shared lib · common Common ops · sync Sync API
Components 20
Backend
Python web service, domain modules, async jobs, and migrations.
- Web app · WSGI entrypoint and main application bootstrap for the Python backend.
server/application.py - Core app · Main backend package wiring config, commands, controller, and app setup.
server/mergin/app.py - Sync API · Core project storage and synchronization domain with public and private APIs, permissions, files, versions, and workspace logic.
server/mergin/sync - Disk store · Storage abstraction and disk-backed project content persistence.
server/mergin/sync/storages/disk.py - Sync jobs · Background work for sync-related processing and maintenance.
server/mergin/sync/tasks.py - Auth · Authentication and account management boundary including bearer/session handling, forms, schemas, controllers, and account tasks.
server/mergin/auth - Stats · Usage analytics and operational reporting subsystem with its own API and tasks.
server/mergin/stats - Celery · Shared background worker runtime used by backend task modules.
server/mergin/celery.py - Telemetry · OpenTelemetry integration for backend instrumentation.
server/mergin/otel - Migrations · Alembic database migrations for project, membership, upload, and versioning tables.
server/migrations
Frontend
Vue/TypeScript applications and shared UI library.
- User app · Main user-facing Vue/TypeScript single-page app for collaboration and account workflows.
web-app/packages/app/src/main.ts - Admin app · Separate admin-facing Vue/TypeScript application.
web-app/packages/admin-app/src/main.ts - Shared lib · Reusable frontend library with common UI, modules, APIs, stores, routes, and theme assets.
web-app/packages/lib/src/main.ts - Project UI · Shared project feature module for listing, collaborators, files, versions, uploads, and sharing.
web-app/packages/lib/src/modules/project - User UI · Shared user feature module for login, profile, password, email verification, and account actions.
web-app/packages/lib/src/modules/user - Admin UI · Admin feature module for accounts, projects, reports, server settings, and update checks.
web-app/packages/admin-lib/src/modules/admin - Shell UI · 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 · Shared container entrypoint, Nginx, SSL proxy, and telemetry assets.
deployment/common - Community stack · Community deployment composition and environment templates.
deployment/community - Enterprise stack · Enterprise deployment with SSO-related services and proxy configuration.
deployment/enterprise
Connections 25
- 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.