# coderdojo/community-platform architecture

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

- Interactive diagram: https://gitdiagram.com/coderdojo/community-platform
- Repository: https://github.com/coderdojo/community-platform

## Overview

##### Project type and purpose
- Zen is a full-stack, microservice-based community platform for CoderDojo (a global network of free coding clubs).
- It consists of a JavaScript/Node.js backend split into multiple microservices, an AngularJS frontend, a ticketing/profile/search platform, two NodeBB-based forums, an ETL pipeline for data import, and integrations (e.g., Mozilla Open Badges).

##### File structure
- This repository is purely documentation (README.md, architecture.md, localisation.md, forums.md, etc.) plus supporting ETL scripts under scripts/zen-etl.
- The core application code lives in three separate microservice repos and one frontend repo (linked from architecture.md).
- The ETL folder includes dump creation, JS scripts to insert dojos/users, packaged with zen.etl.js.

##### Key insights from README
- The system runs as multiple Node.js services and an AngularJS client.
- Two forum services run on NodeBB.
- Data storage uses a relational database accessed by each microservice.
- There’s an external badge-issuing service (Mozilla Open Badges).
- There is a separate local dev environment repo (cp-local-development).

a. Main components
– Frontend (AngularJS SPA)
– API Gateway or aggregator (if present; otherwise direct service calls)
– Microservices (e.g., Dojo service, User service, Ticketing/service)
– Forums cluster (two NodeBB instances)
– Database (shared or per-service schemas)
– ETL pipeline (scripts/zen-etl)
– External services (Mozilla Open Badges API)
b. Relationships and interactions
– Frontend ↔ Microservices (REST/HTTP)
– Microservices ↔ Database (SQL queries, migrations)
– ETL → Database (initial data load)
– Frontend ↔ Forums (via widget or embedded URLs, API calls for auth)
– Services ↔ Open Badges (OAuth or API calls)
c. Architectural patterns/design principles
– Microservices: each service has its own bounded context (Dojo, User, Ticketing)
– Clear separation of concerns: frontend vs. backend vs. ETL vs. forums
– API-first design: all internal and external communications via HTTP APIs
– Documentation-driven: architecture.md as source of truth
d. Key technologies/frameworks
– Node.js for microservices
– AngularJS for frontend
– NodeBB for forums
– PostgreSQL/MySQL (or relational DB)
– JavaScript ETL scripts (zen.etl.js)
– Docker (in cp-local-development) for local dev

##### Detail without overcomplicating
- Every distinct component (microservices, forums, ETL, external).
- Integrations and data stores.
- Special configurations (e.g., migrations, Docker).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Documentation
    subgraph "Documentation"
        README["README.md"]:::doc
        ARCH["architecture.md"]:::doc
        LOC["localisation.md"]:::doc
        FORUMS1["forums.md"]:::doc
        FORUMS2["forums-es.md"]:::doc
        MIGRATES["database-migrates.md"]:::doc
        TESTDATA["creating-test-data.md"]:::doc
    end

    %% Frontend
    subgraph "Frontend"
        Client["AngularJS Client"]:::service
    end

    %% Microservices
    subgraph "Microservices"
        DojoMS["Dojo MS"]:::service
        UserMS["User MS"]:::service
        TicketMS["Ticketing MS"]:::service
    end

    %% Forums
    subgraph "Forums"
        Forum1["NodeBB Forum (Public)"]:::service
        Forum2["NodeBB Community Forum"]:::service
    end

    %% Database
    PostgreSQL[(PostgreSQL)]:::db

    %% ETL Pipeline
    subgraph "ETL Pipeline" 
        ETL["scripts/zen-etl/"]:::etl
        Dump["create-dump.sh"]:::etl
        InsertDojos["insert-dojos.js"]:::etl
        InsertUsers["insert-users.js"]:::etl
        Runner["zen.etl.js"]:::etl
        Upload["upload-dump.sh"]:::etl
        DataFiles["data/"]:::etl
    end

    %% External Services
    OpenBadges((Open Badges API)):::ext

    %% Relationships
    Client -->|REST/HTTP| DojoMS
    Client -->|REST/HTTP| UserMS
    Client -->|REST/HTTP| TicketMS
    Client -->|Embeds/Widget| Forum1
    Client -->|Embeds/Widget| Forum2

    DojoMS -->|SQL Queries| PostgreSQL
    UserMS -->|SQL Queries| PostgreSQL
    TicketMS -->|SQL Queries| PostgreSQL

    ETL -->|Initial Data Load| PostgreSQL
    Dump --> ETL
    InsertDojos --> ETL
    InsertUsers --> ETL
    Runner --> ETL
    Upload --> ETL
    DataFiles --> ETL

    TicketMS -->|Badge Issuance| OpenBadges
    DojoMS -->|Badge Verification| OpenBadges

    %% Click Events - Documentation
    click README "https://github.com/coderdojo/community-platform/blob/master/README.md"
    click ARCH "https://github.com/coderdojo/community-platform/blob/master/architecture.md"
    click LOC "https://github.com/coderdojo/community-platform/blob/master/localisation.md"
    click FORUMS1 "https://github.com/coderdojo/community-platform/blob/master/forums.md"
    click FORUMS2 "https://github.com/coderdojo/community-platform/blob/master/forums-es.md"
    click MIGRATES "https://github.com/coderdojo/community-platform/blob/master/database-migrates.md"
    click TESTDATA "https://github.com/coderdojo/community-platform/blob/master/creating-test-data.md"

    %% Click Events - ETL
    click ETL "https://github.com/coderdojo/community-platform/tree/master/scripts/zen-etl/"
    click Dump "https://github.com/coderdojo/community-platform/blob/master/scripts/zen-etl/create-dump.sh"
    click InsertDojos "https://github.com/coderdojo/community-platform/blob/master/scripts/zen-etl/insert-dojos.js"
    click InsertUsers "https://github.com/coderdojo/community-platform/blob/master/scripts/zen-etl/insert-users.js"
    click Runner "https://github.com/coderdojo/community-platform/blob/master/scripts/zen-etl/zen.etl.js"
    click Upload "https://github.com/coderdojo/community-platform/blob/master/scripts/zen-etl/upload-dump.sh"
    click DataFiles "https://github.com/coderdojo/community-platform/tree/master/scripts/zen-etl/data/"

    %% Styles
    classDef service fill:#D0E6FF,stroke:#6C8EBF
    classDef db fill:#FFF3B0,stroke:#E1B000
    classDef ext fill:#D8F5D8,stroke:#0F8E0F
    classDef etl fill:#E0E0E0,stroke:#888888
    classDef doc fill:#F9F9F9,stroke:#CCCCCC
```
