Codebase Summary
Quick reference for repository structure, file patterns, and service inventory.
Repository Statistics
| Metric |
Count |
| Services (compose.yaml) |
63 |
| Komodo TOML configs |
~65 |
| Categories |
9 |
| Servers |
2 (unraid: 41, development: 22, deploy=false: 1) |
| Pre-commit hooks |
7 |
| ADRs |
3 (Lakekeeper migration, Hyperdrive+Workers, Workers AI via LiteLLM) |
| TF infra modules |
1 (infrastructure/cloudflare/) |
| Python packages |
3 (root + scripts/mikrotik + skills) |
| CF Workers stacks |
2 (workers/ scaffold + template/) |
Directory Tree
docker-compose/
├── stacks/ # Docker Compose source of truth
│ ├── applications/ # 20 services
│ ├── database/ # 10 services
│ ├── data-platform/ # 6 stacks (lakehouse pipeline, see Data Platform section)
│ │ └── compose/
│ │ ├── 10-catalog/ # Legacy Gravitino config (not deployed)
│ │ ├── 15-lakekeeper/ # Lakekeeper + OpenFGA (Iceberg REST catalog)
│ │ ├── 16-opa/ # OPA policy enforcement for Trino
│ │ ├── 30-query/ # Trino (SQL over Iceberg, via Lakekeeper REST)
│ │ ├── 40-streaming/ # Redpanda (tmpfs) + RisingWave v3.0.0 (single_node)
│ │ ├── 50-adapters/ # Push API :8093 + Telegram adapter
│ │ ├── 60-monitoring/ # dp-health-check (60s loop, Apprise alerts)
│ │ └── bootstrap/ # One-shot init scripts + DDL
│ ├── development/ # 4 services
│ ├── llm/ # 5 services
│ ├── monitoring/ # 6 services
│ ├── networking/ # 9 services
│ ├── orchestration/ # 2 services
│ └── storage/ # 2 services
├── analytics/ # dbt projects (streaming + batch)
│ ├── streaming/ # dbt-risingwave (MVs, staging, sinks)
│ └── batch/ # dbt-trino (Iceberg batch models)
├── komodo/stacks/ # Komodo deployment configs
│ ├── root_syncs/ # Infrastructure TOMLs
│ │ ├── resource_sync.toml # One entry per category
│ │ ├── server.toml # Server definitions
│ │ ├── alerter.toml # Ntfy alerting
│ │ └── procedure.toml # Scheduled tasks
│ └── {category}/ # One .toml per service
├── scripts/ # Python automation
│ └── mikrotik/ # Mikrotik scripts (uv workspace member)
├── docs/ # Documentation
│ ├── komodo.md # Full Komodo guide
│ ├── DEPLOYMENT.md # Deployment workflow
│ └── mikrotik-tailscale.md # MikroTik setup
└── .pre-commit-config.yaml # Quality gate definitions
Cloudflare Infrastructure
infrastructure/cloudflare/ # OpenTofu IaC for CF account
├── tofu.tf # Provider ~> 5.22 (Workers VPC support)
├── main.tf # Provider + locals
├── variables.tf # CF account/zone IDs, tunne_id, hyperdrive creds
├── connectivity.tf # cloudflare_connectivity_directory_service (TCP)
├── hyperdrive.tf # 2× cloudflare_hyperdrive_config (cached + fresh)
├── dns-records.tf # 17 DNS records (CNAME + proxied)
├── tunnel.tf # cloudflare_zero_trust_tunnel_cloudflared_config
├── outputs.tf # Outputs: hyperdrive IDs, connectivity service ID
└── tofu.tfstate # R2 backend: tofu-state-minhluc
workers/ # Cloudflare Workers codebase
├── package.json # wrangler 4 + typescript 5.7 + vitest 2 + pg 8.16
├── tsconfig.json # Strict TS for Workers runtime
├── README.md # Workflow doc + 6 prerequisite steps
└── template/ # Workers scaffold (copyable)
├── wrangler.jsonc # 2 Hyperdrive bindings (HYPERDRIVE + HYPERDRIVE_FRESH)
├── src/index.ts # Pattern: cached vs fresh selection
├── test/index.test.ts # Vitest + unstable_dev
└── vitest.config.ts # @cloudflare/vitest-pool-workers
docs/adr/
├── 0001-gravitino-to-lakekeeper-migration.md
├── 0002-cloudflare-hyperdrive-workers-adoption.md
└── 0003-cloudflare-workers-ai-via-litellm.md
Key File Patterns
| File |
Location |
Purpose |
compose.yaml |
stacks/{category}/{service}/ |
Docker Compose source of truth |
compose.env |
stacks/{category}/{service}/ |
Optional local env overrides |
compose.exporters.yaml |
stacks/{category}/{service}/ |
Compose overlay (multi-file) |
{service}.toml |
komodo/stacks/{category}/ |
Komodo deployment config |
resource_sync.toml |
komodo/stacks/root_syncs/ |
Category-level sync config |
server.toml |
komodo/stacks/root_syncs/ |
Server definitions |
Services Inventory
Applications (21)
| Service |
Port(s) |
Purpose |
| aria2 |
— |
Download manager (HTTP/FTP/BT) |
| crawl4ai |
11235 |
Web crawling for AI |
| delphitools |
— |
Delphi development tools |
| emby |
— |
Media server |
| gitea |
2222, 3005 |
Self-hosted git (also CI/CD) |
| homeassistant |
— |
Home automation platform |
| homepage |
8088 |
Service dashboard |
| immich |
2283 |
Photo/video management |
| jellyfin |
8096, 7359/udp |
Media server + HW transcoding |
| koodo |
8182 |
Reader |
| linkding |
— |
Bookmark manager |
| memos |
— |
Self-hosted note-taking (Supabase) |
| nextcloud |
— |
File management + WebDAV (Pigsty DB + RustFS) |
| ntfy |
9282 |
Push notification service |
| protonmail |
1025, 1143 |
Email bridge |
| searxng |
— |
Metasearch engine |
| vaultwarden |
— |
Password manager |
| zalo-tg |
— |
Zalo-Telegram bridge |
Database (11)
| Service |
Port(s) |
Purpose |
| clickhouse |
8123, 9000 |
Columnar analytics DB |
| iceberg |
— |
Table format for data lakehouse |
| mariadb |
3306-host |
MySQL-compatible relational DB |
| meilisearch |
7700, 24900 |
Full-text search engine |
| memgraph |
7444, 7687, 3000 |
Graph database |
| opensearch |
— |
Search and analytics engine |
| pigsty |
5432, 5439 |
PostgreSQL distribution (ParadeDB) |
| postgres |
5432, 5437, 5438 |
PostgreSQL (main, immich, pgvector) |
| postgresus |
4005 |
PostgreSQL instance |
| qdrant |
6333, 6334 |
Vector database |
| redis |
6379 |
In-memory cache / message broker |
| supabase |
8100 (Kong) |
Self-hosted BaaS (PG + Auth + REST + Realtime + Storage + Functions + Studio) |
Development (4)
| Service |
Port(s) |
Purpose |
| agentmemory |
— |
Persistent memory for AI agents |
| bigquery-emulator |
9050, 9060 |
Local BigQuery testing |
| komodo |
9120, 8120 |
Deployment platform (deploy=false) |
| rosetta |
— |
Translation tooling |
LLM (6)
| Service |
Port(s) |
Purpose |
| 9router |
— |
LLM request routing |
| litellm |
4001 |
LLM API gateway |
| odysseus |
— |
Self-hosted AI workspace |
| qmd |
— |
Query management dashboard |
| usage-plan-mcp |
8080 |
Usage tracking MCP server |
Monitoring (6)
| Service |
Port(s) |
Purpose |
| grafana |
3002 |
Dashboards and visualization |
| mimir-loki-tempo |
9009, 3100, 3200, 4327, 4328 |
Metrics, logs, traces backends |
| otel-collector |
4317, 4318, 55679 |
OpenTelemetry collection |
| promtail-dev |
— |
Log shipping (development) |
| uptime-kuma |
3004 |
Uptime monitoring (32 checks) |
Networking (9)
| Service |
Port(s) |
Purpose |
| adguard-home |
53, 784, 853, 3003, 9617 |
DNS ad blocking (primary) |
| adguard-replica |
53, 784, 853, 3004 |
DNS ad blocking (replica, HA) |
| adguard-sync |
— |
Syncs primary→replica every 30min |
| caddy |
80, 443 |
Reverse proxy (macvlan 192.168.100.10) |
| cloudflared-unraid |
— |
Cloudflare Tunnel client |
| gluetun |
— |
VPN client for container traffic |
| mosquitto |
— |
MQTT message broker |
| pmacct |
2055 |
Network traffic accounting |
| vector |
— |
Log/event pipeline |
Storage (2)
| Service |
Port(s) |
Purpose |
| romm |
— |
ROM management + Tinfoil integration |
| Service |
Port(s) |
Purpose |
| data-platform-catalog |
8181 |
Lakekeeper (Rust Iceberg REST catalog, replaces Gravitino) + OpenFGA :8082 auth |
| data-platform-opa |
8282 |
OPA policy enforcement in front of Trino |
| data-platform-query |
8091 |
Trino 482 (SQL over Iceberg, catalog points to Lakekeeper warehouse=homelab) |
| data-platform-streaming |
9092, 8085, 4566, 5691 |
Redpanda v25.3.1 (tmpfs 2GB) + RisingWave v3.0.0 (single_node persistent, 8GB RAM) |
| data-platform-adapters |
8092, 8093 |
Push API :8093 (sole data entry) + Telegram adapter :8092 (login web UI) |
| data-platform-monitoring |
— |
dp-health-check (60s loop, Apprise infra tag on failure) |
| data-platform-analytics |
— |
dbt projects (analytics/streaming + analytics/batch), deployed via scripts/deploy-dbt.sh |
Orchestration (2)
| Service |
Port(s) |
Purpose |
| airflow |
8081 |
Workflow orchestration (GitDagBundle) |
| n8n |
5678 |
Workflow automation + task runners |
| Tool |
Location |
Purpose |
km CLI |
~/.local/bin/km |
Komodo management CLI v1.19.5 |
bd CLI |
system |
Beads issue tracker |
uv |
system |
Python package manager |
pre-commit |
system |
Git hook runner |
| Mikrotik scripts |
scripts/mikrotik/ |
Network automation |
| AdGuard skills |
.claude/skills/adguard/ |
DNS management & debugging |
| Mikrotik debug |
.claude/skills/mikrotik-debug/ |
Network diagnostics |
Config Files
| File |
Purpose |
.pre-commit-config.yaml |
Hook definitions |
.python-version |
Python 3.12 pin |
pyproject.toml |
Python project config (ruff, mypy) |
.dclintrc |
Docker Compose lint rules |
.hadolint.yaml |
Dockerfile lint config |
.yamllint.yml |
YAML lint config |
.infisical.json |
Infisical workspace config |