service-architecture — правило для Claude Code: Docker-сервисы проекта
Правило service-architecture описывает архитектуру Docker-сервисов Polar: общую инфраструктуру и отдельный стек приложения для каждого worktree. Помогает агенту учитывать связи между контейнерами и их адреса.
Apache-2.0 ★ 1 216 обновлён 2026-10-24
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsЧто делает 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-settings2Вручную: положить файлы
.claude/rules/service-architecture.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/service-architecture.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/service-architecture.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/service-architecture.mdВручную: положить файлы
.clinerules/service-architecture.mdПо шагам, с командами для каждой платформы: 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