Service Dependency Map
Visual representation of service dependencies in RavenmaskOS.
Core Dependencies
┌─────────────────┐
│ Traefik │
│ (Edge Router) │
└────────┬────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│PostgreSQL │ │ Redis │ │ Zitadel │
│(Database) │ │ (Cache) │ │ (SSO) │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
┌─────────────┼─────────────┬──────────┴──────────┐ │
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌───────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐
│GitLab │ │ Norns │ │ Bifrost │ │ n8n │ │ OAuth2-Proxy │
└───────┘ │ Agent │ │ API │ │ │ │ │
└────┬─────┘ └────┬─────┘ └──────────┘ └──────────────┘
│ │
└──────┬──────┘
│
▼
┌────────────────┐
│ Bifrost │
│ Executors │
└────────┬───────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐
│ Norns │ │ n8n │ │ Future │
│ Tools │ │Workflows │ │ MCP/API │
└─────────┘ └──────────┘ └──────────┘
Dependency Matrix
Data Layer Dependencies
| Service | PostgreSQL | Redis | Notes |
|---|---|---|---|
| Zitadel | ✓ | Identity data, sessions | |
| Norns Agent | ✓ | ✓ | Tasks, memories, context cache |
| Bifrost | ✓ | ✓ | Tools, channels, session cache |
| GitLab | ✓ | ✓ | Repos, CI/CD, Sidekiq |
| n8n | ✓ | ✓ | Workflows, queue |
| Langfuse | ✓ | LLM traces, sessions | |
| Grafana | ✓ | Dashboards, alerts | |
| Grocy | ✓ | Inventory data |
Identity Dependencies
| Service | Zitadel | OAuth2-Proxy | Notes |
|---|---|---|---|
| GitLab | ✓ | OIDC SSO | |
| n8n | ✓ | ForwardAuth | |
| Norns Admin | ✓ | NextAuth.js OIDC | |
| Bifrost Admin | ✓ | NextAuth.js OIDC | |
| Homepage | ✓ | ForwardAuth | |
| Homebridge | ✓ | ForwardAuth | |
| Grafana | ✓ | OIDC SSO (planned) |
AI Platform Dependencies
┌─────────────────────────────────────────────────────────────────┐
│ AI PLATFORM │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ Ollama │◀─────────────┐ │
│ │ (LLM) │ │ │
│ └──────────────┘ │ │
│ ▲ │ │
│ │ │ │
│ ┌──────┴───────┐ ┌──────┴──────┐ │
│ │ Norns │◀──────│ Bifrost │ │
│ │ Agent │ │ API │ │
│ └──────┬───────┘ └──────┬──────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────┐ │
│ │ LangGraph │ │ Bifrost │ │
│ │ (Workflow) │ │ Admin │ │
│ └──────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Langfuse │ │
│ │ (Tracing) │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Voice Platform Dependencies
┌─────────────────────────────────────────────────────────────────┐
│ VOICE PLATFORM │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Web Voice: │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ LiveKit │──▶│ Voice │──▶│ Whisper │──▶│ Norns │ │
│ │ │ │ Agent │ │ (STT) │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Coturn │ │ Piper │ │ Bifrost │ │
│ │ (TURN) │ │ (TTS) │ │ Tools │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Phone Voice: │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Twilio │──▶│Telephony │──▶│ Deepgram │──▶│ Norns │ │
│ │ (PSTN) │ │(Pipecat) │ │ (STT) │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ElevenLabs│ │ Bifrost │ │
│ │ (TTS) │ │ Tools │ │
│ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Observability Dependencies
┌─────────────────────────────────────────────────────────────────┐
│ OBSERVABILITY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ Grafana │ │
│ │ (Dashboards) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Loki │ │ Tempo │ │ Prometheus │ │
│ │ (Logs) │ │ (Traces) │ │ (Metrics) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ └─────────────────┴─────────────────┘ │
│ │ │
│ ┌──────┴───────┐ │
│ │ Alloy │ │
│ │ (Collector) │ │
│ └──────────────┘ │
│ ▲ │
│ │ │
│ All Containers │
│ │
└─────────────────────────────────────────────────────────────────┘
Startup Order
Critical services must start in dependency order:
1. PostgreSQL, Redis (data stores)
│
▼
2. Traefik (edge router)
│
▼
3. Zitadel (identity - needs postgres)
│
▼
4. OAuth2-Proxy (auth middleware - needs zitadel)
│
▼
5. All other services (can start in parallel)
Docker Compose Dependencies
services:
norns-agent:
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
External Dependencies
| Service | External Dependency | Purpose |
|---|---|---|
| Traefik | AWS Route 53 | DNS-01 TLS challenge |
| Telephony | Twilio | PSTN gateway |
| Telephony | Deepgram | Cloud STT |
| Telephony | ElevenLabs | Cloud TTS |
| Telephony | OpenAI | GPT-4o-mini routing |
| Voice Gateway | OpenAI (optional) | Realtime API |
| Norns | OpenAI/Anthropic | LLM providers |
| GitLab | External SMTP (optional) | Email notifications |
Failure Impact Analysis
PostgreSQL Down
| Affected Service | Impact |
|---|---|
| Zitadel | Critical - No authentication |
| Norns | Critical - No task/memory access |
| Bifrost | Critical - No tool execution |
| GitLab | Critical - No source control |
| n8n | Critical - No workflows |
| Langfuse | High - No tracing |
| Grafana | Medium - Dashboards unavailable |
Redis Down
| Affected Service | Impact |
|---|---|
| Norns | High - Context cache lost |
| n8n | High - Queue processing stops |
| Bifrost | Medium - Session cache lost |
| GitLab | Medium - Sidekiq jobs delayed |
Zitadel Down
| Affected Service | Impact |
|---|---|
| GitLab | High - No SSO login |
| n8n | High - No new logins |
| Norns Admin | High - No admin access |
| All OAuth2-Proxy protected | High - 401 errors |
Traefik Down
| Affected Service | Impact |
|---|---|
| All services | Critical - No external access |
Health Check Cascade
# Check critical path
curl -f http://postgres:5432 || echo "PostgreSQL down"
curl -f http://docs/infrastructure/redis:6379 || echo "Redis down"
curl -f https://auth.ravenhelm.dev/health || echo "Zitadel down"
curl -f https://norns.ravenhelm.dev/health || echo "Norns down"
curl -f https://bifrost-api.ravenhelm.dev/health || echo "Bifrost down"
See Also
- [[Network-Architecture]] - Network topology
- [[Infrastructure]] - Core services
- [[Operations/Disaster-Recovery]] - Recovery procedures