К основному содержанию
правило CX Codex

service-architecture — правило для Claude Code: Docker-сервисы проекта

Правило service-architecture описывает архитектуру Docker-сервисов Polar: общую инфраструктуру и отдельный стек приложения для каждого worktree. Помогает агенту учитывать связи между контейнерами и их адреса.

Apache-2.0 ★ 1 216 обновлён 2026-10-24

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Открыть на GitHub

Что делает service-architecture

Инфраструктура работает в проекте polar-shared: PostgreSQL доступен как db:5432, Redis как redis:6379, MinIO как minio:9000, а аналитика — через tinybird:7181. Для каждого экземпляра приложения предусмотрены своя логическая база polar_dev_<N>, индекс Redis и бакеты MinIO. У общей инфраструктуры нет опубликованных портов хоста: обращаться к ней нужно через dev docker exec <service> ....

Стек polar-app-<N> включает FastAPI API, worker с Dramatiq и Next.js frontend. API запускает миграции и загружает начальные данные при первом старте; web ждёт, пока API станет healthy. Контейнеры приложения подключаются к отдельной сети экземпляра и к polar-shared, но web остаётся вне общей сети, чтобы api:8000 указывал на API своего экземпляра. Monitoring с Prometheus и Grafana включается через --monitoring. Поскольку порты общей инфраструктуры не опубликованы, подключение к ней с хоста через обычный порт не сработает.

Какие задачи решает

  • разделить общую инфраструктуру и стеки приложений по worktree
  • найти адрес PostgreSQL, Redis или MinIO внутри сети Docker
  • понять, какие сервисы должны запуститься до API и frontend
  • проверить, где доступны порты приложения и мониторинга

Примеры запросов агенту

  • Объясни, как устроены Docker-сети и сервисы в polar-app-<N>.
  • Проверь, куда подключаться к PostgreSQL и Redis из контейнера приложения.
  • Почему frontend ждёт API и как включить Prometheus с Grafana?

Как установить service-architecture

1Через маркетплейс плагинов

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings

2Вручную: положить файлы

.claude/rules/service-architecture.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о service-architecture

Как установить service-architecture в Claude Code?

Добавьте маркетплейс командой /plugin marketplace add fcakyon/claude-codex-settings, затем установите плагин командой /plugin install polar-skills@claude-settings. Файл правила: .claude/rules/service-architecture.md.

Что делает правило service-architecture?

Описывает Docker-инфраструктуру Polar, сервисы приложения, сети, зависимости контейнеров и сохранение данных в томах.

Почему web не подключён к сети polar-shared?

Так http://api:8000 разрешается в API своего экземпляра приложения, а не другого стека.

Исходный текст

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

Похожие правила IDE

Все правила IDE по теме «DevOps и инфраструктура» →
infisical-self-host Infisical Скилл infisical-self-host помогает развернуть и настроить серверную платформу Infisical в Docker Compose или Kubernetes. Пригодится при настройке базы данных PostgreSQL, очередей Redis и параметров безопасности. CX Codex +1 834установок docker-compose-production TheBushidoCollective Скилл docker-compose-production готовит конфигурации Docker Compose для продакшена: задаёт лимиты ресурсов, проверки healthcheck, ротацию логов, секреты и изоляцию сетей. CX Codex +1 487установок GitLab Stack Config Generator rknall Скилл GitLab Stack Config Generator раскладывает конфиги nginx, PostgreSQL и Redis по ./config для GitLab-стека, тянет значения из .env и проверяет, что секреты не попали в файлы. CX Codex +1 303установок object-storage devops-skills Скилл object-storage для работы с объектным хранилищем: команды AWS CLI, бакет-политики, lifecycle-правила, версионирование и self-hosted MinIO. CX Codex +1 387установок valkey oakoss Скилл помогает настраивать Valkey и Redis-совместимое хранилище: от кэша и лимитов запросов до очередей и миграции с Redis. Пригодится при проектировании схемы данных и Docker Compose. CX Codex +1 142установок infra-audit SethGammon Скилл infra-audit сканирует docker-compose, env-файлы, ORM-конфиги и строки подключения, чтобы собрать карту инфраструктуры проекта и найти, какого слоя не хватает. CX Codex +1 ★ 937звёзд репо

Из того же набора113

Весь набор →
manage-instances Правило manage-instances для параллельного запуска нескольких изолированных стеков приложения в отдельных worktree, каждый со своей БД, Redis и портами. CX Codex +1 ★ 1 216звёзд репо test-audit Скилл test-audit проверяет новые и изменённые тесты, а также помогает находить дубли и низкоценные проверки. Пригодится перед добавлением тестов и при аудите тестового набора. CX Codex +1 ★ 1 216звёзд репо webmcp-gen Скилл webmcp-gen собирает рабочий процесс сайта в WebMCP-инструмент и проверяет, что он ведёт себя так же, как существующий интерфейс. CX Codex +1 ★ 1 216звёзд репо start-environment Правило start-environment для Claude Code описывает запуск локального окружения через dev docker up: ожидание готовности сервисов и определение назначенных портов. CX Codex +1 ★ 1 216звёзд репо openship-config Скилл openship-config, который готовит репозиторий к деплою на OpenShip: осматривает проект и создаёт openship.json с минимально необходимыми настройками. Пригодится перед первым запуском конфигурации или когда валидатор ругается. CX Codex +1 ★ 1 216звёзд репо app-auth Скилл app-auth для Claude Code проектирует и настраивает аутентификацию. Включается при запросах на вход через соцсети, восстановление пароля, переключение аккаунтов и сохранение профиля. CX Codex +1 ★ 1 216звёзд репо gcloud-usage Скилл gcloud-usage помогает разбирать логи, метрики и трассировки Google Cloud, а также настраивать фильтры и алерты. Пригодится при отладке проблем в GCP. CX Codex +1 ★ 1 216звёзд репо dokploy-deploy Скилл dokploy-deploy подключает к агенту документацию Dokploy: облачную и self-hosted панель, деплой приложений и Docker Compose, базы, домены и индекс CLI-команд. CX Codex +1 ★ 1 216звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой