# badgeteam/badgehub-infra architecture

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

- Interactive diagram: https://gitdiagram.com/badgeteam/badgehub-infra
- Repository: https://github.com/badgeteam/badgehub-infra

## Overview

##### Project Type & Purpose
- This project is an infrastructure-as-code repository using Ansible to provision and configure Debian servers for hosting BadgeHub services. It focuses on configuring system essentials (users, firewall, filesystem, SSH, Docker) and deploying service containers for the BadgeHub API and Keycloak (an authentication service).
- The README clarifies that the infrastructure is built with modular roles for reproducible server configuration suitable for both testing and production environments.

##### Analyzing the File Structure
- Top-Level Files & Directories:
– There are configuration files such as .editorconfig, .gitignore, LICENSE, and README.md.
– Directories like "badgehub" and "keycloak" include Docker Compose files and environment examples, indicating containerized components for the BadgeHub API and authentication via Keycloak.
– The "group_vars" directory holds environment-specific variables for different host groups.
– Ansible playbooks (playbook_dev.yaml, playbook_prod.yaml) are included alongside "roles".
- The “roles” directory contains modular Ansible roles for various infrastructure configurations:
– System: Base package installations, time, and logging settings.
– User: User creation and SSH key configuration.
– UFW: Firewall configuration via UFW.
– Docker: Installation and configuration of Docker along with prune services.
– Filesystem: Creating directories for Docker Compose apps.
– SSH: Configuring SSH daemon settings.
– BadgeHub API: Deployment logic that creates necessary directories and clones the repository.
- Additionally, there are roles that handle Docker configurations and custom templates, indicating a focus on automated, repeatable infrastructure setups.

To accurately capture the architecture:
a. Main components:
– Ansible Controller: Represents the automation engine from where playbooks are executed.
– Target Infrastructure Servers: Debian-based VMs that will be configured.
– Key Infrastructure Components on the target servers:
- System Configuration: Handles base OS setup (system, user, SSH, filesystem, journald).
- Network & Security: UFW configuration (firewall) ensures secure network access.
- Container Management: Docker setup including Docker Compose applications.
- Application Services: Two primary containerized services represented by:
▪ BadgeHub API (in the “badgehub” directory with its Docker Compose file)
▪ Keycloak (in the “keycloak” directory for authentication)
– External Artifacts:
- Preseed scripts and host inventory files that facilitate initial system provisioning and variable injection.

b. Relationships & Interactions:
– The Ansible Controller (via playbooks) connects and pushes configurations to the target Debian servers.
– Each modular role (e.g., system, user, UFW, docker) configures different aspects of the system.
– Docker plays a central role – it manages containerized components. Two key containers (BadgeHub API and Keycloak) are managed via Docker Compose.
– There is a dependency flow: before application deployment, system-level configurations (user, SSH, UFW, system) must be performed to create a secure and stable host environment.
– The Docker role, along with the filesystem role (which creates the necessary directory for Docker Compose), supports the launch of service containers.

c. Architectural Patterns & Design Principles:
– Modular Design: Roles are self-contained and independent, promoting clear separation of concerns.
– Infrastructure as Code: The repository uses Ansible for reproducible, automated configurations.
– Containerization: Docker and Docker Compose are used to encapsulate the BadgeHub API and authentication services.
– Environment-Specific Configuration: Group variable files in “group_vars” enable tailoring the deployment for different environments (development, testing, production).

d. Relevant Technologies & Frameworks:
– Ansible (for orchestration and configuration management)
– Docker & Docker Compose (for container management)
– Debian (target operating system)
– UFW (for firewalling)
– Keycloak (for authentication)
– Various YAML and Jinja2 templates for role configurations

## Diagram (Mermaid)

```mermaid
flowchart TD
    EArtifacts("External Artifacts"):::external
    EnvConfig("Environment Config"):::external
    AC("Ansible Controller"):::ansible
    
    subgraph "Host Configuration"
        SYS("System Configuration"):::config
        UM("User Management"):::config
        SSH("SSH Configuration"):::config
        UFW("UFW Configuration"):::config
        FS("Filesystem Setup"):::config
    end

    DE("Docker Engine"):::docker

    subgraph "Containerized Applications"
        BAPI("BadgeHub API Service"):::container
        KC("Keycloak Service"):::container
    end

    EArtifacts -->|"provides artifacts"| EnvConfig
    EnvConfig -->|"supplies vars"| AC
    AC -->|"executes playbooks on"| SYS
    SYS -->|"triggers"| UM
    UM -->|"configures"| SSH
    SSH -->|"secures"| UFW
    UFW -->|"prepares"| FS
    FS -->|"enables"| DE
    DE -->|"launches"| BAPI
    DE -->|"launches"| KC

    click AC "https://github.com/badgeteam/badgehub-infra/blob/main/ansible.cfg"
    click SYS "https://github.com/badgeteam/badgehub-infra/blob/main/roles/system/tasks/main.yaml"
    click UM "https://github.com/badgeteam/badgehub-infra/blob/main/roles/user/tasks/main.yaml"
    click SSH "https://github.com/badgeteam/badgehub-infra/blob/main/roles/ssh/tasks/main.yaml"
    click UFW "https://github.com/badgeteam/badgehub-infra/blob/main/roles/ufw/tasks/main.yaml"
    click FS "https://github.com/badgeteam/badgehub-infra/blob/main/roles/filesystem/tasks/main.yaml"
    click DE "https://github.com/badgeteam/badgehub-infra/blob/main/roles/docker/tasks/main.yaml"
    click BAPI "https://github.com/badgeteam/badgehub-infra/blob/main/roles/badgehub_api/tasks/main.yaml"
    click KC "https://github.com/badgeteam/badgehub-infra/blob/main/keycloak/docker-compose.yml"
    click EnvConfig "https://github.com/badgeteam/badgehub-infra/blob/main/group_vars/all.yaml"
    click EArtifacts "https://github.com/badgeteam/badgehub-infra/tree/main/preseed"

    classDef ansible fill:#add8e6,stroke:#000,stroke-width:2px
    classDef config fill:#90ee90,stroke:#000,stroke-width:2px
    classDef docker fill:#ffd700,stroke:#000,stroke-width:2px
    classDef container fill:#ffb6c1,stroke:#000,stroke-width:2px
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:2px
```
