# bryanmg20/hosting_project architecture

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

- Interactive diagram: https://gitdiagram.com/bryanmg20/hosting_project
- Repository: https://github.com/bryanmg20/hosting_project

## Overview

##### Project Type and Purpose
- This is a full-stack, container-driven web platform that lets authenticated users spin up isolated Docker containers for their projects.
- It comprises a React-based frontend UI, a Flask-based backend API, an Nginx reverse proxy, an external authentication/DB service (“Roble”), and Docker Engine for running user containers.

##### Key Architectural Components
a. Client (Browser)
- User interacts via a browser on three domains:
- ui.localhost → React UI
- api.localhost → Backend API
- <project>.user.localhost → User’s project container
b. Nginx Reverse Proxy
- Single entry point on port 80.
- Routes requests by hostname to UI, API, or the target project container.
- Implements rate limiting, header injection, WebSocket/SSE support, timeouts.
c. Frontend Service (UI)
- React + Vite app container on port 3000.
- Features: AuthContext (JWT), SSEContext (Server-Sent Events), pages/components for login, dashboard, project management.
d. Backend Service (API)
- Flask app container on port 5000.
- Modules:
- Auth (register/login, JWT generation, integration with Roble Auth)
- Projects (CRUD on projects, orchestrates container creation/deletion)
- Containers (start/stop/restart via Docker API)
- SSE (monitors Docker Engine, streams real-time events)
- Persists metadata in Roble DB via its REST API.
e. External Services
- Roble Auth: external identity provider
- Roble DB: external serverless database (users, projects tables)
f. Docker Engine & User Containers
- Docker Engine runs on the same host.
- For each new project, an image is built (downloaded from GitHub), a container is created and assigned a subdomain.
- Backend communicates with Docker Engine via its API to manage containers.

##### Data Flows and Interactions
- User → Browser
- Navigates to ui.localhost → Nginx → React UI
- UI calls API endpoints at api.localhost → Nginx → Flask API
- UI opens SSE connection to /sse/events → Nginx → Flask SSE module
- Flask API ↔ Roble Auth/DB
- Auth endpoints call external Roble Auth for signup/login
- Project endpoints call Roble DB REST API for CRUD on projects
- Flask API ↔ Docker Engine
- Container endpoints call Docker API to start/stop/restart containers
- Nginx → User Containers
- HTTP requests to <project>.user.localhost are forwarded to that container’s port.
- SSE Events
- Flask SSE monitors Docker Engine events & metrics and pushes them to the open SSE connection.
- React UI listens and updates charts/status in real time.

##### Architectural Patterns & Principles
- Layered (Reverse Proxy → UI/API → External Services → Docker Engine)
- Modular monolith in Flask (separate modules for auth, projects, containers, SSE)
- Event-driven updates via SSE rather than polling
- JWT-based stateless authentication with short-lived access tokens and refresh tokens
- Infrastructure as code via Docker Compose, container isolation per project

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Browser["Browser"]:::client

    %% Reverse Proxy
    Nginx["Nginx Reverse Proxy\n(port 80)\n(rate limiting, routing)"]:::infrastructure

    %% Services Layer
    subgraph "Services"
        direction TB
        UI["UI Service\n(React + Vite)\nui.localhost"]:::service
        API["API Service\n(Flask REST & SSE)\napi.localhost"]:::service
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Auth["Roble Auth\n(identity provider)"]:::external
        DB["Roble DB\n(serverless DB)"]:::external
    end

    %% Docker Infrastructure
    subgraph "Docker Host"
        direction TB
        Engine["Docker Engine"]:::infra
        subgraph "User Containers"
            direction TB
            UC1["<project>.user.localhost\n(Container 1)"]:::container
            UC2["<project>.user.localhost\n(Container N)"]:::container
        end
    end

    %% Flows
    Browser -->|"HTTP: ui.localhost"| Nginx
    Nginx -->|"HTTP: ui.localhost"| UI
    Browser -->|"HTTP: api.localhost"| Nginx
    Nginx -->|"HTTP: api.localhost"| API
    Browser -->|"HTTP: <project>.user.localhost"| Nginx
    Nginx -->|"HTTP: proxy to container"| UC1
    Nginx -->|"HTTP: proxy to container"| UC2

    UI -->|"REST API"| API
    UI -.->|"SSE /sse/events"| API

    API -->|"OAuth/JWT"| Auth
    API -->|"REST CRUD"| DB

    API -->|"Docker API"| Engine
    Engine -->|"creates/controls"| UC1
    Engine -->|"creates/controls"| UC2

    %% Click Events
    click Nginx "https://github.com/bryanmg20/hosting_project/blob/main/nginx/nginx.conf"
    click UI "https://github.com/bryanmg20/hosting_project/tree/main/ui/"
    click API "https://github.com/bryanmg20/hosting_project/tree/main/backend/"
    click Engine "https://github.com/bryanmg20/hosting_project/blob/main/docker-compose.yml"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef infrastructure fill:#DFFFE0,stroke:#2E8B57,color:#2E8B57;
    classDef service fill:#FFE8B0,stroke:#DAA520,color:#DAA520;
    classDef external fill:#E8D0FF,stroke:#6A0DAD,color:#6A0DAD;
    classDef infra fill:#F0F0F0,stroke:#888888,color:#555555;
    classDef container fill:#F7F7F7,stroke:#AAAAAA,color:#333333;
```
