# Architecture

## Topology

```mermaid
flowchart TB
    Internet((Internet))
    Edge[Authenticated tunnel gateway]
    SSO[Identity and SSO]
    Proxy[Internal reverse proxy]

    subgraph Home[Segmented home network]
        subgraph Primary[Primary application host]
            Apps[Household and productivity apps]
            Data[Shared databases and caches]
            Media[Media, photos, and documents]
            Observe[Monitoring and dashboards]
            AI[Always-on AI and search]
        end

        subgraph Storage[Storage and ingestion host]
            Pool[Bulk ZFS storage]
            Arr[Media automation and download pipeline]
            Sync[File synchronization and backups]
            Remote[Remote-support relay]
        end

        subgraph Resilience[Offline and resilience host]
            Offline[Offline knowledge and education]
            HomeAuto[Home automation VM]
            Games[Game-server control plane]
            Secondary[Backup DNS and local AI]
            Agents[Automation and agent services]
        end

        Workstation[GPU operator workstation]
        EdgeNode[Low-power weather and radio node]
    end

    Internet --> Edge --> Proxy
    Proxy --> SSO
    SSO --> Apps
    Apps --> Data
    Apps --> Pool
    Media --> Pool
    Arr --> Pool
    Observe --> Apps
    AI -. optional heavy jobs .-> Workstation
    Secondary -. resilient local path .-> AI
    Agents --> Apps
    Sync --> Workstation
    EdgeNode --> Agents
    Remote -. private overlay .-> Workstation
```

## Host responsibilities

### Primary application host

The primary host carries the application plane:

- shared PostgreSQL, MariaDB, and Redis
- identity, SSO, ingress routing, and tunnel clients
- media front ends, photo management, and document management
- dashboards, monitoring, metrics, logs, and notifications
- household applications and workflow automation
- light-tier model serving, search, RAG, and vector storage
- self-hosted development and administration tools

The host is intentionally not the only copy of storage, DNS, or offline knowledge.

### Storage and ingestion host

The storage host owns the large-capacity data plane and workloads that benefit from data locality:

- ZFS-backed bulk datasets
- media acquisition, organization, and post-processing
- synchronized document storage with versioning
- backup targets and retained application data
- private remote-support rendezvous and relay
- selected CPU-only inference utilities
- a secondary DNS replica

### Offline and resilience host

The resilience host is designed to remain useful when public services are unavailable:

- offline reference libraries and educational content
- local notes and browser utilities
- local model and vector services
- agent memory and household helper applications
- Home Assistant running in a dedicated virtual machine
- game-server management
- mesh-radio observation
- a secondary DNS replica

### GPU workstation

The workstation provides high-performance GPU capacity for interactive or heavy jobs. Routine background tasks must continue when it is asleep or offline.

### Low-power edge node

The edge node handles always-on weather and mesh-radio functions close to the attached hardware. It reports upstream but is not part of the main application failure domain.

## Request flows

### External application request

```text
client → tunnel gateway → internal reverse proxy → SSO policy → application
```

The tunnel endpoint is the primary public routing layer for HTTP applications. Application containers do not require direct inbound router exposure; narrowly scoped non-HTTP exceptions are documented and isolated separately.

### Internal application request

```text
trusted client → internal DNS → application or reverse proxy → service
```

### AI request

```text
application → model gateway → always-on local model
                            ↘ optional GPU workstation
```

### Storage request

```text
application host → authenticated network storage mount → storage dataset
```

## Failure-domain rules

1. Losing the GPU workstation must not stop routine automation.
2. Losing public DNS must not be confused with losing the private DNS zone.
3. Losing the primary application host must not destroy bulk datasets or backups.
4. A tunnel or SSO failure must not expose an application directly.
5. The offline host must retain useful local content without WAN access.
6. Changes to storage, networking, identity, and databases require explicit rollback points.