Skip to main content
rule CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Open on GitHub

What 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-settings

2Manually: put the files in place

.claude/rules/service-architecture.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for DevOps and infrastructure →

From the same set113

The whole set →
manage-instances manage-instances — a rule for running multiple isolated app stacks in separate worktrees, each with its own database, Redis index, and host ports. CX Codex +1 ★ 1,216repo stars test-audit The test-audit skill reviews new and changed tests, and helps spot duplicates or low-value checks. Use it when adding tests or auditing an existing suite. CX Codex +1 ★ 1,216repo stars webmcp-gen webmcp-gen turns a page workflow into a WebMCP tool and checks that the tool matches the behavior of the existing UI. CX Codex +1 ★ 1,216repo stars start-environment start-environment teaches the assistant how to spin up local development containers via dev docker up, wait for healthchecks, and inspect ports. CX Codex +1 ★ 1,216repo stars openship-config Inspects a repository and builds openship.json with only the overrides OpenShip needs. Use it before a first deploy or when openship config validate fails. CX Codex +1 ★ 1,216repo stars app-auth The app-auth skill for Claude Code structures and implements application authentication flows. It activates when handling social login, password recovery, account switching, or sign-in components. CX Codex +1 ★ 1,216repo stars gcloud-usage gcloud-usage is a Claude Code skill that guides Google Cloud log queries and analysis of metrics, traces, and alerts. It supports production debugging and GCP observability work. CX Codex +1 ★ 1,216repo stars dokploy-deploy dokploy-deploy hands the agent Dokploy's own docs: cloud and self-hosted setup, app and Compose deploys, databases, domains, plus a CLI command index. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open