# 2-immerse/get-started architecture

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

- Interactive diagram: https://gitdiagram.com/2-immerse/get-started
- Repository: https://github.com/2-immerse/get-started

## Overview

##### Project type and purpose
- From the README and directory layout, this is an open-source, container-based platform for object-based multi-screen broadcasting (the “2-IMMERSE Object-based Broadcasting Platform”).
- It provides reusable components (microservices) orchestrated across cloud and client devices to render media, handle user interaction, and implement DMApp logic.
- The project includes build scripts (`build/`), deployment scripts for Docker Compose (`deployment/`), documentation (`docs/`), and example apps (`examples/`).

##### File structure
- Top level:
- `build/` – build instructions & scripts that produce Docker images or binaries.
- `deployment/` – Docker-Compose YAML (`docker-compose-standalone.yml`), HAProxy config, health check scripts.
- `examples/` – sample DMApps, e.g., an EPG JSON config.
- No application source code in this repo, so the focus is on orchestration, deployment, and examples.

##### Readme insights
- Core stack: containerized microservices + HbbTV 2.0/HTML5 JavaScript clients.
- Deployment targets: any container orchestration (Docker-Compose shown as example).
- Clients fetch DMApps from the service platform and render them.

##### Main components
a. Build & CI pipeline
- Source repo → build scripts → container registry (private or public).
b. Deployment platform
- Docker-Compose (or Kubernetes cluster) hosting:
- API Gateway / Load Balancer (HAProxy)
- Microservices:
– Session Manager
– Device Registry
– Content Manager / Asset Service
– DMApp Orchestrator
– (Optional) Message Broker
- Data stores:
– Persistent DB (e.g., PostgreSQL, MongoDB)
– In-memory cache (e.g., Redis)
c. Clients
- HbbTV-compliant browsers on TVs, web browsers on second screen devices, mobile apps.
- They host HTML/CSS/JS DMApps.
d. Examples
- EPG configuration file (e.g., `examples/epg/epg.json`) that the platform loads to demonstrate scheduling.

##### Relationships and interactions
- Clients ←→ HAProxy/API Gateway (HTTPS)
- Gateway routes to appropriate microservice endpoints.
- Microservices communicate via HTTP/REST or message bus.
- Services read/write to databases or caches.
- Health checks (`health.sh`) feed status into the load balancer.
- Build pipeline pushes new images to registry; deploy scripts pull and launch updated containers.

##### Architectural patterns & design principles
- Microservices: each service handles a single responsibility (session, device, content, orchestration).
- Containerization: isolates services, consistent environment, easy scaling.
- API Gatekeeping: HAProxy as a reverse proxy and load balancer.
- Infrastructure as code: deployment described in YAML, scripts versioned in repo.
- Pluggability: example DMApps loaded via configuration, extensible with new apps.

##### Detail level
- Containers defined in `docker-compose-standalone.yml`.
- If the `software-stack.svg` lists additional components (message broker, CDN), include them.
- Ports, protocols (HTTP/HTTPS, AMQP), and any volume mounts (for persistence).
- Boundaries (e.g., “On-prem / Cloud”, “Private network”, “Public Internet”).

##### Final checklist for the principal software engineer
- [ ] Sketch Docker-Compose cluster with containers (load balancer, services, DB, cache).
- [ ] Illustrate clients pulling DMApps over HTTP.
- [ ] Capture health-check flows and auto-scaling points (if applicable).
- [ ] Reference the example EPG flow: config → Content Manager → client UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Pipeline
    subgraph "Build & CI Pipeline"
        GitRepo["Git Repository"]:::external
        BuildScripts["Build Scripts"]:::pipeline
        BuildReadme["Build README"]:::pipeline
    end
    GitRepo -->|"push code"| BuildScripts
    BuildScripts -->|"guidance"| BuildReadme
    BuildScripts -->|"produce images"| Registry["Docker Registry"]:::external

    click BuildScripts "https://github.com/2-immerse/get-started/tree/master/build/"
    click BuildReadme "https://github.com/2-immerse/get-started/blob/master/build/README.md"

    %% Deployment Cluster
    subgraph "Docker-Compose Cluster" 
        direction TB
        ComposeFile["docker-compose-standalone.yml"]:::deployment
        HAProxy["HAProxy (API Gateway)"]:::gateway
        HealthScript["Health Check Script"]:::deployment
        DeployReadme["Deployment README"]:::deployment
        DeployTODO["Deployment TODOs"]:::deployment

        subgraph "Microservices"
            direction TB
            Session["Session Manager Service"]:::microservice
            Device["Device Registry Service"]:::microservice
            Content["Content Manager / Asset Service"]:::microservice
            Orchestrator["DMApp Orchestrator Service"]:::microservice
            Broker["Message Broker"]:::microservice
        end

        subgraph "Data Stores"
            direction TB
            Postgres["PostgreSQL DB"]:::db
            Redis["Redis Cache"]:::db
        end
    end

    Registry -->|"pull images"| ComposeFile
    ComposeFile --> HAProxy
    ComposeFile --> Session
    ComposeFile --> Device
    ComposeFile --> Content
    ComposeFile --> Orchestrator
    ComposeFile --> Broker
    ComposeFile --> Postgres
    ComposeFile --> Redis
    HAProxy -->|health check| HealthScript
    ComposeFile --> DeployReadme
    ComposeFile --> DeployTODO

    click ComposeFile "https://github.com/2-immerse/get-started/blob/master/deployment/docker-compose-standalone.yml"
    click HAProxy "https://github.com/2-immerse/get-started/blob/master/deployment/haproxy/haproxy.cfg"
    click HealthScript "https://github.com/2-immerse/get-started/blob/master/deployment/health.sh"
    click DeployReadme "https://github.com/2-immerse/get-started/blob/master/deployment/README.md"
    click DeployTODO "https://github.com/2-immerse/get-started/blob/master/deployment/TODO.md"

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocsRoot["Documentation Root"]:::docs
        ArchDiagram["Architecture Overview Diagram"]:::docs
        GovernanceDoc["Governance Documentation"]:::docs
        DocsTODO["Documentation TODOs"]:::docs
    end

    DocsRoot --> ArchDiagram
    DocsRoot --> GovernanceDoc
    DocsRoot --> DocsTODO

    click DocsRoot "https://github.com/2-immerse/get-started/tree/master/docs/"
    click ArchDiagram "https://github.com/2-immerse/get-started/blob/master/docs/software-stack.svg"
    click GovernanceDoc "https://github.com/2-immerse/get-started/blob/master/docs/governance.md"
    click DocsTODO "https://github.com/2-immerse/get-started/blob/master/docs/TODO.md"

    %% Examples
    subgraph "Examples"
        direction TB
        ExamplesReadme["Examples README"]:::examples
        EPJS["EPG Sample Configuration"]:::examples
    end

    ExamplesReadme --> EPJS

    click ExamplesReadme "https://github.com/2-immerse/get-started/blob/master/examples/README.md"
    click EPJS "https://github.com/2-immerse/get-started/blob/master/examples/epg/epg.json"

    %% Project Overview
    ProjectReadme["Project README"]:::external
    ProjectReadme

    click ProjectReadme "https://github.com/2-immerse/get-started/blob/master/README.md"

    %% Clients
    subgraph "Clients"
        direction TB
        TV["HbbTV Browser"]:::client
        Web["Web Browser"]:::client
        Mobile["Mobile App"]:::client
    end

    TV -->|HTTPS| HAProxy
    Web -->|HTTPS| HAProxy
    Mobile -->|HTTPS| HAProxy

    %% Legend
    subgraph "Legend"
        direction TB
        A["Microservice"]:::microservice
        B["Database / Cache"]:::db
        C["API Gateway"]:::gateway
        D["Pipeline / Deployment"]:::deployment
        E["Docs / Examples"]:::docs
        F["Clients"]:::client
    end

    %% Styles
    classDef external fill:#eee,stroke:#999
    classDef pipeline fill:#cde,stroke:#036
    classDef deployment fill:#def,stroke:#048
    classDef microservice fill:#f9f,stroke:#933
    classDef db fill:#bbf,stroke:#338
    classDef gateway fill:#bfb,stroke:#3a3
    classDef docs fill:#ffd,stroke:#d93
    classDef examples fill:#fed,stroke:#d63
    classDef client fill:#ffb,stroke:#f80
```
