# openstreetmap/stateofthemap-2025 architecture

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

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

## Overview

- Content Repository: Represent the Git-controlled repository which contains all source files. Break this down into components:
- Markdown Content (e.g., in “calls” and “venue” directories; index.html, imprint)
- Templates: “_layouts” folder (layouts for pages, sessions, redirect, etc.)
- Includes: “_includes” folder (partial HTML snippets like header, footer, nav, CSS and JS includes)
- Static Assets: “css”, “js”, “img”, “fonts" directories.
- Additional Assets: Supporting files such as “LICENSE”, “.editorconfig”, and configuration files (e.g., _config.yml for Jekyll configuration)

- Jekyll Build Process: Show how Jekyll reads the configuration (_config.yml), uses the layouts and includes to merge with markdown content, and generates the final static HTML files.
- Directly indicate the use of the Jekyll static site generator and how it processes markdown files and transforms them into HTML using Liquid templates.

- Development and Deployment Environment:
- Local Development: Show the developer’s local environment running Jekyll via “jekyll serve” on port 4000.
- Containerized Environment: Represent Docker (Dockerfile, docker-compose.yml, and docker-compose.override.yml) as an alternative build/run method.
- CI/CD Pipeline: Optionally include the GitHub Actions workflows (in .github/workflows) that might auto-test or deploy the site upon incoming commits or pull requests.

- External Integration:
- Although the site is static, note that the program schedule (sessions) is managed externally via the Pretalx submission system. Add an external component for Pretalx (an external service) that feeds data (indirectly through API or automated updates) into the website.

##### Relationships and Data Flow
- Content and templates from the repository feed into the Jekyll build process.
- The Jekyll engine processes templates, markdown, and assets to output a static site.
- The resulting static site is then served (either via the local “jekyll serve” mechanism or in production via a web server, potentially running inside a Docker container).
- A note on external updates from the Pretalx system: indicate that changes on the submission system may automatically update specific parts of the generated content (e.g., sessions).
- Optionally, link CI/CD steps (GitHub Workflows) that run test/build procedures before deployment.

##### Architectural Patterns & Technologies
- Static Site Generation: Emphasize that Jekyll is central as it converts markdown and templates into a static website.
- Separation of Concerns: Organize components into content, presentation (layouts, includes, CSS/JS), and build/deployment pipelines.
- Containerization: Mention Docker components (Dockerfile, docker-compose) that encapsulate the Jekyll environment.
- Version Control & CI/CD: Show how source versioning (Git) and GitHub Actions integrate into the overall workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository Subgraph
    subgraph "Source Repository"
        A1["calls (Markdown)"]:::repo
        A2["codeofconduct (Markdown)"]:::repo
        A3["imprint (HTML)"]:::repo
        A4["venue (Markdown)"]:::repo
        A5["Homepage (HTML)"]:::repo
        A6["Jekyll Layouts"]:::repo
        A7["HTML Partials"]:::repo
        A8["CSS Assets"]:::repo
        A9["JavaScript Assets"]:::repo
        A10["Image Assets"]:::repo
        A11["Font Assets"]:::repo
        A12["Configuration Files"]:::repo
        A13["Docker & Compose"]:::repo
        A14["GitHub Workflows"]:::repo
        RepoEnd["Repository Summary"]:::repo_agg
    end

    %% Aggregated arrow from Repository to Build Process
    RepoEnd -->|"feeds"| B["Jekyll Build Process"]:::build

    %% CI/CD Pipeline triggers Build Process
    F["CI/CD Pipeline"]:::cideploy -->|"triggers"| B

    %% Build Process generates Static Site Output
    B -->|"generates"| C["Static Site Output"]:::deploy

    %% Deployment Options from Static Site Output
    C --> D["Local Jekyll Server (port 4000)"]:::deploy
    C --> E["Docker-based Environment"]:::deploy
    D -->|"serves"| G["User/Browser"]:::deploy
    E -->|"serves"| G

    %% External Integration feeds Static Site Output
    H["External Pretalx System"]:::external -->|"updates"| C

    %% Click Events for Source Repository Components
    click A1 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/calls/general.md"
    click A2 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/codeofconduct/index.md"
    click A3 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/imprint/index.html"
    click A4 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/venue/index.md"
    click A5 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/index.html"
    click A6 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/_layouts/default.html"
    click A7 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/_includes/about.html"
    click A8 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/css/leaflet.css"
    click A9 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/js/bootstrap.js"
    click A10 "https://github.com/openstreetmap/stateofthemap-2025/tree/main/img"
    click A11 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/fonts/icon.eot"
    click A12 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/_config.yml"
    click A13 "https://github.com/openstreetmap/stateofthemap-2025/tree/main/Dockerfile"
    click A14 "https://github.com/openstreetmap/stateofthemap-2025/blob/main/.github/workflows/ci.yml"

    %% Click Events for Other Components
    click B "https://github.com/openstreetmap/stateofthemap-2025/blob/main/_config.yml"
    click E "https://github.com/openstreetmap/stateofthemap-2025/blob/main/docker-compose.yml"

    %% Class Definitions
    classDef repo fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef repo_agg fill:#F9E79F,stroke:#BA4A00,stroke-width:2px;
    classDef build fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef deploy fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef cideploy fill:#F9E79F,stroke:#AF7AC5,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
