# itzderock/hostforge architecture

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

- Interactive diagram: https://gitdiagram.com/itzderock/hostforge
- Repository: https://github.com/itzderock/hostforge

## Overview

##### Main Components
The system should be divided into these primary components:

a) Frontend Layer:
- Next.js Application (src/app directory)
- Authentication System (src/app/(auth))
- Dashboard Interface (src/app/(dashboard))
- Project Management UI (src/app/(dashboard)/project)
- Settings Management (src/app/(dashboard)/settings)

b) Backend Layer:
- TRPC API Server (src/server/api)
- Authentication Service (src/server/auth)
- Build System (src/server/build)
- Docker Integration (src/server/docker)
- Database Layer (src/server/db)
- Managers (src/server/managers)

c) External Services:
- Docker Swarm
- Prometheus (for monitoring)
- GitHub (for source code)
- Traefik (for routing)

##### Component Relationships

**[Frontend Layer]**
- ↓ ↑ (TRPC)
**[Backend Layer]**
- ↓ ↑
**[External Services Layer]**

##### Specific Implementation Details

Key architectural elements:

a) Service Flow:
- User Authentication Flow
- Project Deployment Pipeline
- Container Management Flow
- Monitoring and Metrics Flow

b) Data Flow:
- GitHub Repository → Build System → Docker Images
- User Commands → Service Manager → Docker Swarm
- Metrics Collection → Prometheus → Dashboard

##### Important Architectural Patterns to Highlight

- Microservices Architecture (Docker Swarm)
- Event-Driven Architecture (Deployment system)
- Type-Safe API Layer (TRPC)
- Module-based Structure (src/server/modules)

##### Key Integration Points

- Docker Swarm Integration (src/server/docker)
- GitHub Integration (src/server/build/sources)
- Prometheus Monitoring (src/server/modules/stats)
- Traefik Routing (src/server/docker/traefik.ts)

##### Security Boundaries

Isolation between:
- Project Networks
- Authentication Boundaries
- Service Isolation

##### The role of Traefik in routing requests

This system design should reflect Hostforge's core feature of simplifying Docker Swarm management while maintaining security and automation capabilities.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#e67e22,stroke:#d35400,color:white
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef critical fill:#e74c3c,stroke:#c0392b,color:white

    %% Frontend Layer
    subgraph Frontend
        NextApp["Next.js Application"]:::frontend
        Auth["Authentication UI"]:::frontend
        Dashboard["Dashboard Interface"]:::frontend
        ProjectUI["Project Management UI"]:::frontend
        Settings["Settings Management"]:::frontend
    end
    click NextApp "https://github.com/itzderock/hostforge/tree/main/src/app"
    click Auth "https://github.com/itzderock/hostforge/tree/main/src/app/(auth)"
    click Dashboard "https://github.com/itzderock/hostforge/tree/main/src/app/(dashboard)"
    click ProjectUI "https://github.com/itzderock/hostforge/tree/main/src/app/(dashboard)/project"
    click Settings "https://github.com/itzderock/hostforge/tree/main/src/app/(dashboard)/settings"

    %% Backend Layer
    subgraph Backend
        TRPC["TRPC API Server"]:::backend
        AuthService["Authentication Service"]:::backend
        BuildSystem["Build System"]:::backend
        DockerIntegration["Docker Integration"]:::backend
        Database["Database Layer"]:::database
        
        subgraph Managers
            ProjectManager["Project Manager"]:::backend
            ServiceManager["Service Manager"]:::backend
            BuildManager["Build Manager"]:::backend
            DeployManager["Deployment Manager"]:::backend
            ServiceGen["Service Generation"]:::backend
        end
        
        subgraph Integrations
            PrometheusInt["Prometheus Integration"]:::backend
            GitHubInt["GitHub Integration"]:::backend
            TraefikInt["Traefik Integration"]:::backend
        end
    end
    click TRPC "https://github.com/itzderock/hostforge/tree/main/src/server/api"
    click AuthService "https://github.com/itzderock/hostforge/tree/main/src/server/auth"
    click BuildSystem "https://github.com/itzderock/hostforge/tree/main/src/server/build"
    click DockerIntegration "https://github.com/itzderock/hostforge/tree/main/src/server/docker"
    click Database "https://github.com/itzderock/hostforge/tree/main/src/server/db"
    click ProjectManager "https://github.com/itzderock/hostforge/blob/main/src/server/managers/Project.ts"
    click ServiceManager "https://github.com/itzderock/hostforge/blob/main/src/server/managers/Service.ts"
    click BuildManager "https://github.com/itzderock/hostforge/blob/main/src/server/build/BuildManager.ts"
    click DeployManager "https://github.com/itzderock/hostforge/blob/main/src/server/managers/Deployment.ts"
    click ServiceGen "https://github.com/itzderock/hostforge/blob/main/src/server/managers/ServiceGeneration.ts"
    click PrometheusInt "https://github.com/itzderock/hostforge/blob/main/src/server/modules/stats/Prometheus.ts"
    click GitHubInt "https://github.com/itzderock/hostforge/blob/main/src/server/build/sources/GitHub.ts"
    click TraefikInt "https://github.com/itzderock/hostforge/blob/main/src/server/docker/traefik.ts"

    %% External Services
    subgraph External
        DockerSwarm["Docker Swarm"]:::external
        Prometheus["Prometheus"]:::external
        GitHub["GitHub"]:::external
        Traefik["Traefik"]:::external
    end

    %% Relationships
    NextApp --> TRPC
    Auth --> AuthService
    Dashboard --> TRPC
    ProjectUI --> TRPC
    Settings --> TRPC

    TRPC --> ProjectManager
    TRPC --> ServiceManager
    TRPC --> BuildManager
    TRPC --> DeployManager

    ProjectManager --> Database
    ServiceManager --> Database
    BuildManager --> Database
    DeployManager --> Database

    BuildSystem --> GitHubInt
    GitHubInt --> GitHub
    BuildManager --> BuildSystem

    DockerIntegration --> DockerSwarm
    ServiceManager --> DockerIntegration
    DeployManager --> DockerIntegration

    PrometheusInt --> Prometheus
    TraefikInt --> Traefik

    ServiceGen --> ServiceManager

    %% Legend
    subgraph Legend
        Frontend_L["Frontend Component"]:::frontend
        Backend_L["Backend Component"]:::backend
        External_L["External Service"]:::external
        Database_L["Database Component"]:::database
        Critical_L["Critical Component"]:::critical
    end
```
