service-architecture — Claude Code rule for Docker services
The service-architecture rule maps Polar’s shared Docker infrastructure and per-worktree app stacks. Use it to understand service addresses, container dependencies, and network boundaries.
Apache-2.0 ★ 1,216 updated 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsWhat service-architecture does
The shared project, polar-shared, runs PostgreSQL at db:5432, Redis at redis:6379, MinIO at minio:9000, and analytics at tinybird:7181. Each app instance gets a logical database named polar_dev_<N>, a Redis DB index, and MinIO buckets. Shared infrastructure exposes no host ports; access it with dev docker exec <service> ....
Each polar-app-<N> stack contains a FastAPI API, a Dramatiq worker, and a Next.js frontend. On its first start, the API runs migrations and loads seed data. The web service waits for a healthy API. App containers join an instance-specific bridge and polar-shared, while web stays off the shared network so api:8000 resolves to its own instance. Optional Prometheus and Grafana services are enabled with --monitoring. Because shared services publish no host ports, connecting to them from the host through their container ports will fail.
What it helps with
- separate shared infrastructure from per-worktree app stacks
- find Docker network addresses for PostgreSQL, Redis, and MinIO
- check which containers must start before the API and frontend
- locate app and monitoring ports
Example prompts for the agent
- Explain how Docker networking works for
polar-app-<N>. - Find the PostgreSQL and Redis addresses for an app container.
- Why does the frontend wait for the API, and how do I enable Prometheus and Grafana?
How to install service-architecture
1Plugin marketplace
/plugin marketplace add fcakyon/claude-codex-settings/plugin install polar-skills@claude-settings2Manually: put the files in place
.claude/rules/service-architecture.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/service-architecture.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/service-architecture.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/service-architecture.mdManually: put the files in place
.clinerules/service-architecture.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about service-architecture
How do I install service-architecture in Claude Code?
Add the marketplace with /plugin marketplace add fcakyon/claude-codex-settings, then install the plugin with /plugin install polar-skills@claude-settings. The rule file is .claude/rules/service-architecture.md.
What does the service-architecture rule do?
It documents Polar’s Docker infrastructure, app services, container dependencies, networks, and persistent volumes.
Why is web kept off the polar-shared network?
This makes http://api:8000 resolve to the API belonging to that app instance.
Source text
service-architecture.md · Apache-2.0
--- title: Service Architecture Reference category: Reference tags: architecture, services, infrastructure --- # Service Architecture Reference Two Docker projects: shared infra (`polar-shared`, one per machine) and a per-instance app stack (`polar-app-<N>`, one per worktree). Shared infra publishes **no host ports** — reach it with `dev docker exec <service> ...`. ## Infrastructure services (project `polar-shared`) ### db (PostgreSQL 15.1) - Primary database. Reached at `db:5432` on the `polar-shared` network. - Credentials: `polar` / `polar`. - One logical database per instance: `polar_dev_<N>`. - Volume: `postgres_data`. Health check: `pg_isready`. ### redis (Redis Alpine) - Cache and job-queue backend at `redis:6379`. - One DB index per instance (`<N>`); launched with `--databases 100`. - Health check: `redis-cli ping`. ### minio (S3-compatible storage) - File storage at `minio:9000` (container) or `localhost:9000` (host). - Console at `localhost:9001` with credentials `polar-development` / `polar123456789`. - Per-instance buckets: `polar-s3-<N>`, `polar-s3-public-<N>`. - Volume: `minio_data`. ### tinybird - Analytics engine at `tinybird:7181` (admin `7182`). Token is auto-discovered from the running container on api startup. ## Application services (project `polar-app-<N>`) ### api (FastAPI backend) - `python:3.14.6-slim` + uvicorn, hot-reload on. - Host port: `8000` (instance 0) or `8100+N`. - Healthcheck: `curl /healthz` (generous `start_period` covers first-boot sync + migrations + seed). - Startup: `uv sync`, build email templates, bootstrap DB/buckets, run migrations, load seed data on first run. ### worker (background jobs) - Same image as api. No host port. - Dramatiq with the priority queues (`high_priority`, `medium_priority`, `low_priority`), hot-reload on. - Waits for api before starting. ### web (Next.js frontend) - `node:24-slim` + Turbopack, hot-reload on. - Host port: `3000` (instance 0) or `3100+N`. Memory limit: 6 GB. - Healthcheck via Node's built-in `fetch` (the image has no curl/wget). - Waits for api to be **healthy** before starting (it proxies SSR to api). ## Optional monitoring (project `polar-shared`, `--monitoring`) - **prometheus** — metrics, 1-day retention, at `prometheus:9090` (no host port). - **grafana** — dashboards at `grafana:3000` internally, login `polar` / `polar` (no host port; port-forward if you need the UI). ## Container dependencies ``` minio-setup → minio (healthy) api → db, redis, minio-setup worker → api (started) web → api (healthy) grafana → prometheus ``` ## Volume persistence | Volume | Purpose | |--------|---------| | postgres_data | Database (shared) | | minio_data | Files (shared) | | server_uv_cache | Python package cache | | api_venv / worker_venv | Per-service virtualenv | | pnpm_store | Node package store | | web_node_modules | Frontend deps | | web_next_cache | Build cache | ## Networking App containers join a per-instance `default` bridge plus `polar-shared`. Infra is addressed by name (`db:5432`, `redis:6379`, `minio:9000`, `api:8000`). Web stays off `polar-shared` so `http://api:8000` resolves to *this* instance's api.
© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings