# mapswipe/mapswipe-backend architecture

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

- Interactive diagram: https://gitdiagram.com/mapswipe/mapswipe-backend
- Repository: https://github.com/mapswipe/mapswipe-backend

## Overview

##### Project type and purpose
- This is a monolithic Django-based backend service exposing a GraphQL API, used by the MapSwipe mobile/web clients.
- It also runs background jobs (via Celery) for tasks like data aggregation and tile generation, and serves a tile-map service.

##### File structure
- Top-level “main/” contains Django settings, ASGI/WSGI entrypoints, GraphQL schema bootstrap, middlewares, Celery setup.
- “apps/” holds Django apps organized by domain (common, user, project, mapping, contributor, community_dashboard, tutorial). Each app has models, serializers, GraphQL types/queries/mutations, Celery tasks, migrations, tests.
- “utils/” contains shared helper modules (geo/tile_server for tile generation, graphql helpers, common utilities).
- Docker/Helm manifests for containerized deployment; docker-compose.yaml for local development; helm/ for Kubernetes charts.
- Supporting files: .github workflows (CI, helm publish), pre-commit, pytest.ini.

##### README for additional insights
- The service boots via “docker compose up” exposing “web”, “worker” and “worker-beat” services.
- It uses environment variables (via .env) to configure Django, the database, Redis, and third-party integrations.
- Provides GraphQL schema generation, Django migrations, and pytest integration.

a. Main components
- API Layer: Django web service (Gunicorn/Uvicorn) hosting GraphQL endpoint and Django Admin.
- Background Workers: Celery worker & Celery-beat processes.
- Message Broker & Cache: Redis (broker for Celery, also used for caching or rate-limiting).
- Primary Database: PostgreSQL (persistent storage for all Django models).
- Tile Server Module: internal Python service (utils/geo/tile_server) invoked by API or tasks to serve map tiles or group them.
- External Clients: MapSwipe mobile & web apps, third-party integrations (e.g. Sentry for error logging).
- DevOps/CI: Docker Registry, GitHub Actions, Helm/Kubernetes.

b. Relationships & interactions
- Clients → HTTP/GraphQL → Web container → Reads/writes → Postgres.
- Web container → enqueues tasks → Redis broker → Celery worker → processes task → writes back to DB or publishes tile data to tile service.
- Celery-beat (scheduler) → enqueues periodic tasks (e.g. aggregated data updates).
- Web container & Celery workers → publish errors/logs → Sentry.
- Web container → cache lookups → Redis (optional).
- DevOps pipeline → builds Docker images → pushes → Helm chart deploys to k8s.

c. Architectural patterns & design principles
- Monolithic Django with clearly separated domain apps.
- GraphQL façade with DataLoader pattern to batch & cache DB calls.
- Asynchronous task queue for long-running or scheduled jobs.
- Utility libraries extracted under “utils/” to avoid duplication.
- Containerized micro-services pattern for web & worker processes.
- Infrastructure-as-code via Helm charts for reproducible deployments.

d. Technologies & frameworks
- Python 3.x, Django, Graphene-Django (GraphQL), Celery, Redis, PostgreSQL.
- Docker, Docker Compose, Kubernetes (Helm), GitHub Actions.
- Sentry for error tracking, pytest for testing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Clients" 
        direction TB
        Client["MapSwipe Mobile/Web"]:::external
        Sentry["Sentry (Error Tracking)"]:::external
    end

    subgraph "Django Web Service" 
        direction TB
        Web["Gunicorn/Uvicorn\nGraphQL API & Admin"]:::compute
        subgraph "Entrypoints & Config"
            direction TB
            ASGI["main/asgi.py"] 
            WSGI["main/wsgi.py"]
            URLs["main/urls.py"]
            Schema["main/graphql/schema.py"]
        end
        subgraph "Domain Apps"
            direction TB
            CommonApp["apps/common"] 
            UserApp["apps/user"] 
            ProjectApp["apps/project"] 
            MappingApp["apps/mapping"] 
            ContributorApp["apps/contributor"] 
            DashboardApp["apps/community_dashboard"] 
            TutorialApp["apps/tutorial"]
        end
        subgraph "Utilities"
            direction TB
            TileUtils["utils/geo/tile_server"] 
            CommonUtils["utils/common.py"]
            GraphQLUtils["utils/graphql"]
        end
    end

    subgraph "Data Layer"
        direction TB
        Postgres[(PostgreSQL)]:::storage
        Redis[(Redis)]:::storage
    end

    subgraph "Background Processing"
        direction TB
        Worker["Celery Worker"]:::compute
        Beat["Celery-beat Scheduler"]:::compute
    end

    subgraph "DevOps & CI/CD"
        direction TB
        DevDocker["Dockerfile & Compose"]:::devops
        DevCI[".github/workflows"]:::devops
        DevHelm["helm/"]:::devops
    end

    Client -->|"HTTP/GraphQL"| Web
    Web -->|"SQL"| Postgres
    Web -->|"Cache"| Redis
    Web -->|"Enqueue AMQP Tasks"| Redis
    Redis -->|"Broker AMQP"| Worker
    Worker -->|"DB Writes/Reads"| Postgres
    Worker -->|"Tile Generation"| TileUtils
    Beat -->|"Schedule Tasks"| Redis
    Web -->|"Error Logs"| Sentry
    Worker -->|"Error Logs"| Sentry
    DevCI -->|"Build & Push Images"| DevDocker
    DevDocker -->|"Deploy Charts"| DevHelm

    click ASGI "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/asgi.py"
    click WSGI "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/wsgi.py"
    click URLs "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/urls.py"
    click Schema "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/graphql/schema.py"
    click CommonApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/common/"
    click UserApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/user/"
    click ProjectApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/project/"
    click MappingApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/mapping/"
    click ContributorApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/contributor/"
    click DashboardApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/community_dashboard/"
    click TutorialApp "https://github.com/mapswipe/mapswipe-backend/tree/develop/apps/tutorial/"
    click TileUtils "https://github.com/mapswipe/mapswipe-backend/tree/develop/utils/geo/tile_server/"
    click CommonUtils "https://github.com/mapswipe/mapswipe-backend/blob/develop/utils/common.py"
    click GraphQLUtils "https://github.com/mapswipe/mapswipe-backend/tree/develop/utils/graphql/"
    click Worker "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/celery.py"
    click Beat "https://github.com/mapswipe/mapswipe-backend/blob/develop/misc/dev/run_worker_beat.sh"
    click Redis "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/cache.py"
    click Postgres "https://github.com/mapswipe/mapswipe-backend/blob/develop/main/db.py"
    click DevDocker "https://github.com/mapswipe/mapswipe-backend/blob/develop/docker-compose.yaml"
    click DevCI "https://github.com/mapswipe/mapswipe-backend/blob/develop/.github/workflows/ci.yml"
    click DevHelm "https://github.com/mapswipe/mapswipe-backend/tree/develop/helm/"

    classDef compute fill:#D0E8FF,stroke:#0288D1,stroke-width:2px
    classDef storage fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
    classDef external fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px
    classDef devops fill:#ECEFF1,stroke:#546E7A,stroke-width:2px
```
