# Service Dependency Map

*Last Updated: 2026-02-26*

This document provides a comprehensive visual and reference guide for understanding service dependencies in the homelab infrastructure.

---

## Architecture Layers

```
┌─────────────────────────────────────────────────────────────────────┐
│                        EXTERNAL ACCESS                              │
│    Cloudflare → DDNS → Home Router → Nginx Proxy Manager           │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    CORE INFRASTRUCTURE LAYER                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │
│  │  Authentik  │  │     NPM     │  │ Prometheus  │  │  Vault    │  │
│  │  (SSO)      │  │ (Proxy)     │  │ (Monitoring)│  │ (Secrets) │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      APPLICATION LAYER                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │  Media   │ │   Dev    │ │   Comms  │ │  Photos  │ │Productivy│  │
│  │  Stack   │ │  Stack   │ │  Stack   │ │  Stack   │ │  Stack   │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Critical Service Dependencies

### Tier 1: Foundation Services
These services must be running for other services to function:

| Service | Host | Port | Dependencies | Depended By |
|---------|------|------|--------------|-------------|
| **Nginx Proxy Manager** | Calypso | 80, 443 | Docker | All web services |
| **Authentik** | Calypso | 9000 | PostgreSQL, Redis | All SSO-enabled services |
| **Vaultwarden** | Atlantis | 8080 | SQLite | Credential storage |
| **Prometheus** | Homelab VM | 9090 | Node exporters | Grafana, Alertmanager |

### Tier 2: Operational Services
These depend on Tier 1 and support multiple other services:

| Service | Host | Dependencies | Depended By |
|---------|------|--------------|-------------|
| **Grafana** | Homelab VM | Prometheus | Dashboards |
| **Alertmanager** | Homelab VM | Prometheus | ntfy, Signal |
| **Pi-hole** | Multiple | Network | DNS resolution |
| **AdGuard Home** | Concord NUC | Network | DNS filtering |
| **Syncthing** | Multiple | Storage | Config sync |
| **PostgreSQL** | Various | Storage | Authentik, Gitea |
| **Redis** | Various | Memory | Authentik, caching |

### Tier 3: Application Services
End-user services that depend on Tiers 1-2:

| Category | Services | Dependencies |
|----------|----------|--------------|
| **Media** | Plex, Jellyfin, arr-stack | Media storage, network |
| **Communication** | Matrix, Mastodon, Mattermost | Authentik, PostgreSQL |
| **Photos** | Immich | PostgreSQL, S3/Local storage |
| **Development** | Gitea, Portainer | PostgreSQL, Docker |
| **Productivity** | Paperless, Wallabag, Reactive Resume | Storage, Auth (optional) |

---

## Service Dependency Graph

### Authentication Flow
```
User → NPM (SSL) → Authentik (OIDC) → Service
                     ↑
                     └── Redis (sessions)
                     └── PostgreSQL (users)
```

### Monitoring Flow
```
Node Exporters → Prometheus → Alertmanager → ntfy
                     │
                     └── Grafana (dashboards)
```

### Media Stack Flow
```
Prowlarr (indexers)
    ↓
Sonarr/Radarr/Lidarr (requests)
    ↓
qBittorrent/SABnzbd (downloads)
    ↓
Plex/Jellyfin (streaming)
```

### External Access Flow
```
Internet → Cloudflare → Home Router → NPM → Service
                                        ↓
                                   Authentik (if enabled)
```

---

## Host Service Mapping

### Atlantis (Synology DS1821+)
- **Primary Role**: Media server, Vaultwarden, Immich
- **Services**: Vaultwarden, Immich, Ollama, Plex
- **Critical Dependencies**: Storage volumes, network

### Calypso (Synology DS723+)
- **Primary Role**: Infrastructure, Proxy, Auth
- **Services**: NPM, Authentik, Paperless, Reactive Resume
- **Critical Dependencies**: Storage volumes

### Concord NUC
- **Primary Role**: DNS, AdGuard, Light services
- **Services**: AdGuard Home, various lightweight apps
- **Critical Dependencies**: Network

### Homelab VM
- **Primary Role**: Monitoring, CI/CD
- **Services**: Prometheus, Grafana, Alertmanager, Gitea Runner
- **Critical Dependencies**: Prometheus data volume

### RPi5
- **Primary Role**: Edge/Immich
- **Services**: Immich (edge)
- **Critical Dependencies**: Network, storage mount

---

## Startup Order

When bringing up the infrastructure after a complete outage:

### Phase 1: Hardware & Network (0-5 min)
1. Synology NAS (Atlantis, Calypso)
2. Network equipment (router, switches)
3. Home Assistant (Zigbee/Z-Wave)

### Phase 2: Core Services (5-15 min)
1. **Vaultwarden** - Access to credentials
2. **PostgreSQL** - Database foundation
3. **Redis** - Session/caching
4. **Authentik** - SSO identity
5. **Nginx Proxy Manager** - External access

### Phase 3: Monitoring (15-20 min)
1. **Prometheus** - Metrics collection
2. **Node Exporters** - System metrics
3. **Grafana** - Dashboards
4. **Alertmanager** - Notifications

### Phase 4: Applications (20-45 min)
1. **Syncthing** - Config sync
2. **Media Stack** - Plex, arr applications
3. **Communication** - Matrix, Mastodon
4. **Development** - Gitea, Portainer
5. **Productivity** - Paperless, etc.

### Phase 5: Optional (45+ min)
1. Gaming servers
2. AI/ML services (Ollama)
3. Experimental applications

---

## Failure Impact Analysis

| Service Down | Impact | Affected Services |
|--------------|--------|-------------------|
| **NPM** | External access broken | All web services |
| **Authentik** | SSO broken | Grafana, Portainer, SSO-enabled apps |
| **Prometheus** | Monitoring silent | Grafana, Alertmanager |
| **Vaultwarden** | Can't access credentials | All (if credentials needed) |
| **Atlantis (NAS)** | Storage issues | Media, Immich, Vaultwarden |
| **Pi-hole** | DNS issues | Local network |

---

## Checking Dependencies

### Docker Compose
```bash
cd hosts/synology/atlantis
docker-compose config
```

### Portainer
1. Open Portainer → Stacks → Select stack
2. View "Service dependencies" in the UI

### Ansible Dependency Map
```bash
ansible-playbook ansible/automation/playbooks/container_dependency_map.yml
```

---

## Common Dependency Issues

### Service Won't Start
1. Check logs: `docker-compose logs <service>`
2. Verify dependency is running: `docker ps | grep <dependency>`
3. Check restart policy

### Intermittent Failures
1. Check resource availability (CPU, memory, disk)
2. Verify network connectivity between hosts
3. Check for circular dependencies

### After Reboot
1. Verify Docker starts automatically
2. Check container restart policies
3. Monitor logs for startup order issues

---

*For detailed troubleshooting, see [Troubleshooting Guide](../troubleshooting/common-issues.md)*