142 lines
4.5 KiB
Markdown
142 lines
4.5 KiB
Markdown
# 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.
|