# openstreetmap/openstreetmap-website architecture

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

- Interactive diagram: https://gitdiagram.com/openstreetmap/openstreetmap-website
- Repository: https://github.com/openstreetmap/openstreetmap-website

## Overview

##### Main components of the system
- Frontend & Integrated Editor: Since the project includes the integrated version of the iD editor and browse pages, clearly indicate a “Frontend” or “Web UI” component (representing the views, assets in “app/assets”, and public code in “public/”).
- Database: As a PostgreSQL-dependant Rails application, show the “Database (PostgreSQL)” with connections to Rails (including ActiveRecord models under “app/models”). You might also note that there are migrations and a “db” folder that define data schema and indexes.
- Auxiliary Components: Optionally, illustrate parts like the integrated GPX processing (see lib/gpx.rb and the API endpoints under “app/controllers/api”) and any support libraries used (e.g., for rate limiting or geolocation).

##### Relationships and interactions
- API endpoints interfacing with external requests (via the “api” controllers) and the client applications.
- Background jobs and asynchronous processing as part of the Rails system that interacts with the database and external systems.

##### Important architectural patterns and design principles
- MVC Pattern: Clearly indicate the separation of concerns between Models (data and business logic), Views (presentation), and Controllers (request handling).
- RESTful API: Emphasize that many parts of the system expose RESTful endpoints (API v0.6) and that the routing (config/routes.rb) organizes these resources.
- Background Job Processing: Indicate that jobs like trace_importer_job and trace_destroyer_job function asynchronously.

##### Relevant technologies and frameworks
- Ruby on Rails, PostgreSQL, and the use of standard Rails libraries/frameworks.
- Various dependencies (from Gemfile); you might mention libraries related to OAuth2, i18n, error handling, file uploads (ActiveStorage), background job processing, etc.
- Docker and Vagrant files hint at containerized development and provisioning strategies, so you might also include deployment/infrastructure layers if that helps your audience.

##### Elements
– From user browsers to the Web UI and then to the Rails Application.
– Between the Rails App and Database (bidirectional).
– From Rails App to external services (outgoing requests).
– From background jobs back to the Database or external notifications.
- Notations for frameworks/technology stacks attached to each component (e.g., “Ruby on Rails” on the Rails App, “PostgreSQL” on the Database, “Docker/Vagrant” on the deployment layer if desired).

##### Final advice

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User Browser"]:::user

    %% Frontend Subgraph
    subgraph "Frontend"
        FE1["Frontend Assets"]:::frontend
        FE2["Public iD Editor"]:::frontend
        FE3["Site Views"]:::frontend
        FE4["Browse Views"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend"
        RA["Rails Application (MVC)"]:::backend
        RC["Rails Configuration"]:::backend
        RR["Routes"]:::backend
        API["API Layer"]:::backend
        APIV["API Views"]:::backend
        BGP["Background Job Processor"]:::backend
        TIP["Trace Importer Job"]:::backend
        TDP["Trace Destroyer Job"]:::backend
        GPX["GPX Processing"]:::auxiliary
    end

    %% Database
    DB["Database (PostgreSQL)"]:::database

    %% External Services Subgraph
    subgraph "External Services"
        OAuth["OAuth Provider"]:::external
        Geo["Geocoding Service"]:::external
        Tile["Map Tile Server"]:::external
        Trans["Translation Service"]:::external
    end

    %% Connections
    U -->|"accesses"| FE1
    U -->|"accesses"| FE2
    U -->|"accesses"| FE3
    U -->|"accesses"| FE4

    FE1 -->|"sends requests"| RA
    FE2 -->|"sends requests"| RA
    FE3 -->|"sends requests"| RA
    FE4 -->|"sends requests"| RA

    RA -->|"executes"| RC
    RA -->|"executes"| RR
    RA -->|"handles"| API
    API -->|"renders"| APIV
    RA -->|"delegates jobs"| BGP
    BGP -->|"processes"| TIP
    BGP -->|"processes"| TDP
    RA -->|"updates"| GPX

    RA <-->|"CRUD operations"| DB
    BGP -->|"updates|DB"| DB

    RA -->|"calls"| OAuth
    RA -->|"calls"| Geo
    RA -->|"calls"| Tile
    RA -->|"calls"| Trans

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cce,stroke:#333,stroke-width:2px;
    classDef backend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef database fill:#afa,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#ffc,stroke:#333,stroke-width:2px;

    %% Click Events
    click RA "https://github.com/openstreetmap/openstreetmap-website/tree/master/app"
    click RC "https://github.com/openstreetmap/openstreetmap-website/blob/master/config/application.rb"
    click RR "https://github.com/openstreetmap/openstreetmap-website/blob/master/config/routes.rb"
    click API "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/controllers/api"
    click APIV "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/views/api"
    click FE1 "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/assets"
    click FE2 "https://github.com/openstreetmap/openstreetmap-website/tree/master/public/iD"
    click FE3 "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/views/site"
    click FE4 "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/views/browse"
    click DB "https://github.com/openstreetmap/openstreetmap-website/tree/master/db"
    click BGP "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/jobs"
    click TIP "https://github.com/openstreetmap/openstreetmap-website/blob/master/app/jobs/trace_importer_job.rb"
    click TDP "https://github.com/openstreetmap/openstreetmap-website/blob/master/app/jobs/trace_destroyer_job.rb"
    click OAuth "https://github.com/openstreetmap/openstreetmap-website/tree/master/app/models/oauth2_application"
    click Geo "https://github.com/openstreetmap/openstreetmap-website/blob/master/lib/nominatim.rb"
    click Tile "https://github.com/openstreetmap/openstreetmap-website/blob/master/config/banners.yml"
    click GPX "https://github.com/openstreetmap/openstreetmap-website/blob/master/lib/gpx.rb"
```
