# devallek/homeserverconfig architecture

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

- Interactive diagram: https://gitdiagram.com/devallek/homeserverconfig
- Repository: https://github.com/devallek/homeserverconfig

## Overview

1. **Nature of the repo**  
   This is not an application codebase; it is a **centralized home-server configuration and documentation repo** for a Debian-based machine named *Firebat*. The repository is split into two architectural layers: **OS-level services** and **Dockerized service stacks**.

2. **Host platform boundary**  
   The physical host is a small home server running **Debian 13.0.1** on an **Intel N100 / 16 Go RAM / SSD** setup. The repo documents how to turn that host into a multi-service server rather than describing a single product.

3. **OS configuration layer (`OsConfig/`)**  
   This folder contains server-side operational guides and scripts for services that live directly on the OS, not in containers. It covers **SSH**, **Samba**, **XRDP**, and **Cloudflared**, plus a bootstrapping script (`AutoConfig.sh`) and terminal customization via **Starship**.

4. **Remote administration and access paths**  
   The host is designed for both command-line and GUI administration: **SSH** is the primary remote control path, **XRDP** provides remote desktop access, and **Cloudflared** adds a zero-trust / tunnel-based access boundary for services or host endpoints without exposing them directly.

5. **File-sharing subsystem**  
   **Samba** is the main host-level file-sharing layer. It exposes shared folders from the Debian machine to the local network, making the server both a compute node and a storage/access point.

6. **Docker orchestration layer (`Docker/`)**  
   Each service group has its own directory with a dedicated **docker-compose.yml** and, when needed, an environment file. The architecture is intentionally **stack-based and isolated**: each folder is one independently managed deployment boundary.

7. **Core application stacks**  
   The Docker layer includes multiple functional stacks:
   - **Portfolio**: WordPress + MySQL + phpMyAdmin
   - **Domotique**: Home Assistant + Eclipse Mosquitto
   - **JellyPack**: Jellyfin-centric media stack with additional supporting services
   - **N8N**: workflow automation / integration platform
   - **Uptime Kuma**: service monitoring
   - **YouTrack**: project management
   - **DNSAdBlock**: DNS-level ad blocking / filtering stack

8. **Internal data flows between services**  
   The most explicit service-to-service dependency in the repo is the **Portfolio** stack: **WordPress** depends on **MySQL**, and **phpMyAdmin** is used to inspect/manage that database. In **Domotique**, **Home Assistant** is paired with **MQTT** via Mosquitto, indicating event-driven home automation messaging.

9. **Operational separation and persistence**  
   The repo’s structure suggests a deliberate separation between **documentation**, **configuration**, and **runtime state**. Environment files such as `portfolio.env` and `youtrack.env` isolate sensitive or stack-specific settings, while the compose files define service lifecycles independently.

10. **What to draw in an architecture diagram**  
   A good diagram would show:
   - one **Debian host** at the center,
   - a left/top branch for **OS services** (SSH, Samba, XRDP, Cloudflared),
   - a right/bottom branch for **Docker stacks** (Portfolio, Domotique, JellyPack, N8N, Uptime Kuma, YouTrack, DNSAdBlock),
   - and internal arrows only where the repo clearly defines dependencies, especially **WordPress → MySQL** and **Home Assistant ↔ Mosquitto**.

Main entry points: [`Docker`](https://github.com/devallek/homeserverconfig/tree/main/Docker) (Docker Stacks), [`OsConfig`](https://github.com/devallek/homeserverconfig/tree/main/OsConfig) (OS Config), [`Docker/Portfolio`](https://github.com/devallek/homeserverconfig/tree/main/Docker/Portfolio) (Portfolio), [`Docker/Domotique`](https://github.com/devallek/homeserverconfig/tree/main/Docker/Domotique) (Domotique)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_repo_root["Repo"]
end

subgraph group_host["Host"]
  node_firebat["Firebat<br/>debian-host"]
end

subgraph group_os["OS layer"]
  node_osconfig["OS Config<br/>host-ops"]
  node_autoconfig["Bootstrap<br/>script<br/>[AutoConfig.sh]"]
  node_ssh["SSH<br/>remote-access<br/>[SrvSSH.md]"]
  node_samba[("Samba<br/>file-sharing<br/>[SrvSamba.md]")]
  node_xrdp["XRDP<br/>remote-desktop<br/>[SrvXRP.md]"]
  node_cloudflared{{"Cloudflared<br/>tunnel-access<br/>[Cloudflared.md]"}}
  node_starship["Starship<br/>shell-prompt"]
end

subgraph group_docker["Docker layer"]
  node_docker_root["Docker Stacks<br/>compose-orchestration"]
  node_portfolio["Portfolio<br/>web-stack"]
  node_wordpress["WordPress<br/>cms"]
  node_mysql[("MySQL<br/>database")]
  node_phpmyadmin["phpMyAdmin<br/>db-admin"]
  node_domotique["Domotique<br/>home-automation"]
  node_homeassistant["Home Assistant<br/>automation-core"]
  node_mosquitto["Mosquitto<br/>mqtt-broker"]
  node_jellypack["JellyPack<br/>media-stack"]
  node_n8n["N8N<br/>automation-platform"]
  node_uptimekuma["Uptime Kuma<br/>monitoring"]
  node_youtrack["YouTrack<br/>project-management"]
  node_dnsadblock{{"DNSAdBlock<br/>dns-filtering"}}
end

node_repo_root -->|"documents"| node_osconfig
node_repo_root -->|"documents"| node_docker_root
node_firebat -->|"runs"| node_osconfig
node_firebat -->|"hosts"| node_docker_root
node_osconfig -->|"bootstrap"| node_autoconfig
node_osconfig -->|"admin access"| node_ssh
node_osconfig -->|"sharing"| node_samba
node_osconfig -->|"gui access"| node_xrdp
node_osconfig -->|"tunnel"| node_cloudflared
node_osconfig -->|"shell UX"| node_starship
node_docker_root -->|"deploys"| node_portfolio
node_docker_root -->|"deploys"| node_domotique
node_docker_root -->|"deploys"| node_jellypack
node_docker_root -->|"deploys"| node_n8n
node_docker_root -->|"deploys"| node_uptimekuma
node_docker_root -->|"deploys"| node_youtrack
node_docker_root -->|"deploys"| node_dnsadblock
node_portfolio -->|"contains"| node_wordpress
node_portfolio -->|"contains"| node_mysql
node_portfolio -->|"contains"| node_phpmyadmin
node_wordpress -->|"reads/writes"| node_mysql
node_phpmyadmin -.->|"manages"| node_mysql
node_domotique -->|"contains"| node_homeassistant
node_domotique -->|"contains"| node_mosquitto
node_homeassistant -->|"publishes/subscribes"| node_mosquitto
node_mosquitto -.->|"events"| node_homeassistant

click node_osconfig "https://github.com/devallek/homeserverconfig/tree/main/OsConfig"
click node_autoconfig "https://github.com/devallek/homeserverconfig/blob/main/OsConfig/AutoConfig.sh"
click node_ssh "https://github.com/devallek/homeserverconfig/blob/main/OsConfig/SrvSSH.md"
click node_samba "https://github.com/devallek/homeserverconfig/blob/main/OsConfig/SrvSamba.md"
click node_xrdp "https://github.com/devallek/homeserverconfig/blob/main/OsConfig/SrvXRP.md"
click node_cloudflared "https://github.com/devallek/homeserverconfig/blob/main/OsConfig/Cloudflared.md"
click node_starship "https://github.com/devallek/homeserverconfig/tree/main/OsConfig/Starship"
click node_docker_root "https://github.com/devallek/homeserverconfig/tree/main/Docker"
click node_portfolio "https://github.com/devallek/homeserverconfig/tree/main/Docker/Portfolio"
click node_domotique "https://github.com/devallek/homeserverconfig/tree/main/Docker/Domotique"
click node_jellypack "https://github.com/devallek/homeserverconfig/tree/main/Docker/JellyPack"
click node_n8n "https://github.com/devallek/homeserverconfig/tree/main/Docker/N8N"
click node_uptimekuma "https://github.com/devallek/homeserverconfig/tree/main/Docker/UptimeKuma"
click node_youtrack "https://github.com/devallek/homeserverconfig/tree/main/Docker/YouTrack"
click node_dnsadblock "https://github.com/devallek/homeserverconfig/tree/main/Docker/DNSAdBlock"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo_root toneBlue
class node_firebat toneAmber
class node_osconfig,node_autoconfig,node_ssh,node_samba,node_xrdp,node_cloudflared,node_starship toneMint
class node_docker_root,node_portfolio,node_wordpress,node_mysql,node_phpmyadmin,node_domotique,node_homeassistant,node_mosquitto,node_jellypack,node_n8n,node_uptimekuma,node_youtrack,node_dnsadblock toneRose
```

## Components

### Repository

Documentation and configuration for the home server

- **Repo**: config-repo · Centralized home-server documentation and configuration

### Host

Physical Debian machine boundary

- **Firebat**: debian-host · Debian 13 home server on Intel N100 hardware

### OS layer

Direct-on-host services and bootstrap configuration

- [OS Config](https://github.com/devallek/homeserverconfig/tree/main/OsConfig): host-ops · Host-level service guides and bootstrap scripts · `OsConfig`
- [Bootstrap](https://github.com/devallek/homeserverconfig/blob/main/OsConfig/AutoConfig.sh): script · Initial host provisioning and setup script · `OsConfig/AutoConfig.sh`
- [SSH](https://github.com/devallek/homeserverconfig/blob/main/OsConfig/SrvSSH.md): remote-access · Primary command-line remote administration · `OsConfig/SrvSSH.md`
- [Samba](https://github.com/devallek/homeserverconfig/blob/main/OsConfig/SrvSamba.md): file-sharing · Network shares exposed from the host · `OsConfig/SrvSamba.md`
- [XRDP](https://github.com/devallek/homeserverconfig/blob/main/OsConfig/SrvXRP.md): remote-desktop · GUI access path to the host · `OsConfig/SrvXRP.md`
- [Cloudflared](https://github.com/devallek/homeserverconfig/blob/main/OsConfig/Cloudflared.md): tunnel-access · Zero-trust tunnel boundary for host endpoints and services · `OsConfig/Cloudflared.md`
- [Starship](https://github.com/devallek/homeserverconfig/tree/main/OsConfig/Starship): shell-prompt · Terminal customization profiles for host usage · `OsConfig/Starship`

### Docker layer

Isolated compose-based service stacks

- [Docker Stacks](https://github.com/devallek/homeserverconfig/tree/main/Docker): compose-orchestration · Directory of isolated docker-compose deployments · `Docker`
- [Portfolio](https://github.com/devallek/homeserverconfig/tree/main/Docker/Portfolio): web-stack · WordPress-based site stack · `Docker/Portfolio`
- **WordPress**: cms · Main content application
- **MySQL**: database · Persistence layer for the Portfolio stack
- **phpMyAdmin**: db-admin · Database inspection and administration UI
- [Domotique](https://github.com/devallek/homeserverconfig/tree/main/Docker/Domotique): home-automation · Home Assistant and MQTT automation stack · `Docker/Domotique`
- **Home Assistant**: automation-core · Automation control plane
- **Mosquitto**: mqtt-broker · Event messaging broker for home automation
- [JellyPack](https://github.com/devallek/homeserverconfig/tree/main/Docker/JellyPack): media-stack · Jellyfin-centric media services · `Docker/JellyPack`
- [N8N](https://github.com/devallek/homeserverconfig/tree/main/Docker/N8N): automation-platform · Workflow automation and integrations · `Docker/N8N`
- [Uptime Kuma](https://github.com/devallek/homeserverconfig/tree/main/Docker/UptimeKuma): monitoring · Service and endpoint monitoring · `Docker/UptimeKuma`
- [YouTrack](https://github.com/devallek/homeserverconfig/tree/main/Docker/YouTrack): project-management · Issue tracking and project management stack · `Docker/YouTrack`
- [DNSAdBlock](https://github.com/devallek/homeserverconfig/tree/main/Docker/DNSAdBlock): dns-filtering · DNS-level ad blocking and filtering stack · `Docker/DNSAdBlock`

## Connections

- Repo → OS Config: documents · Repository includes host-level operational guidance
- Repo → Docker Stacks: documents · Repository includes compose-managed service stacks
- Firebat → OS Config: runs · OS services live directly on the host
- Firebat → Docker Stacks: hosts · Docker deployments run on the Debian machine
- OS Config → Bootstrap: bootstrap · Initial provisioning script
- OS Config → SSH: admin access · Primary remote shell path
- OS Config → Samba: sharing · Host file sharing service
- OS Config → XRDP: gui access · Remote desktop access path
- OS Config → Cloudflared: tunnel · Zero-trust access boundary
- OS Config → Starship: shell UX · Terminal prompt customization
- Docker Stacks → Portfolio: deploys · Independent compose stack
- Docker Stacks → Domotique: deploys · Independent compose stack
- Docker Stacks → JellyPack: deploys · Independent compose stack
- Docker Stacks → N8N: deploys · Independent compose stack
- Docker Stacks → Uptime Kuma: deploys · Independent compose stack
- Docker Stacks → YouTrack: deploys · Independent compose stack
- Docker Stacks → DNSAdBlock: deploys · Independent compose stack
- Portfolio → WordPress: contains · Main application in the stack
- Portfolio → MySQL: contains · Database backend in the stack
- Portfolio → phpMyAdmin: contains · Database administration component
- WordPress → MySQL: reads/writes · WordPress depends on MySQL persistence
- phpMyAdmin → MySQL: manages · phpMyAdmin operates on the MySQL database
- Domotique → Home Assistant: contains · Automation control application
- Domotique → Mosquitto: contains · MQTT broker in the automation stack
- Home Assistant → Mosquitto: publishes/subscribes · Event-driven home automation messaging
- Mosquitto → Home Assistant: events · Broker delivers MQTT messages back to automation
