version: "1.0.0" name: scaffold-service description: >- Scaffold a thin FastAPI router or gRPC servicer under services/{domain}/v{n}/ with AppUtils bootstrap. Use for "add an endpoint/route/API", "expose via REST/gRPC", or "new API version".

Scaffold ArchiPy Service

Read first

Read these plugin rules in full before generating files (paths relative to this skill directory; Claude Code: ${CLAUDE_SKILL_DIR}/../../rules/):

• ../../rules/architecture-for-apps.mdc
• ../../rules/using-archipy-services.mdc
• ../../rules/config-and-di.mdc

Before writing files

1. Inspect existing transports, domain DTOs/logics, app bootstrap, DI wiring, and service tests.
2. Infer domain, API version, framework, and sync/async style when established by the repository.
3. Ask only for unresolved choices. Default to v1 and FastAPI only when no project convention exists.
4. Preserve existing routes, servicers, and bootstrap code; integrate without overwriting.

Prefer ArchiPy

uv add "archipy[fastapi]"   # HTTP
uv add "archipy[grpc]"      # gRPC

Generate

services/<domain>/v{n}/
└── <domain>_service.py

FastAPI

• Thin router: request → domain *InputDTO → logic → *OutputDTO.
• Export create_<domain>_v{n}_router(container) for manage.py / app factory.
• Map domain errors to HTTP status; no business rules / atomic UoW decorators here.

gRPC

• Thin servicer calling logic; sync servicers with AppUtils.create_grpc_app, async with create_async_grpc_app.
• Export register_<domain>_v{n}_servicers(server, container) that adds the servicers to a server built by

AppUtils; the entrypoint and the BDD harness (/scaffold-bdd) both call it, so neither binds a port inside it.

• Do not mix sync/async servicer styles on one server.

Bootstrap (entrypoint)

Prefer AppUtils — do not hand-roll bare FastAPI() / grpc.server():

from archipy.helpers.utils.app_utils import AppUtils
from archipy.configs.base_config import BaseConfig
app = AppUtils.create_fastapi_app()
app.include_router(create_<domain>_v1_router(container))

uvicorn in manage.py from config.FASTAPI (SERVE_HOST, SERVE_PORT, RELOAD, PROXY_HEADERS, FORWARDED_ALLOW_IPS).

Do not

• Version in path (v1, v2), not in business logic.
• Do not re-implement CORS/exception handlers/stock gRPC interceptors AppUtils already wires.
• Wire logic via DI container.
• Never hardcode host/port.

Verify

1. Run the repository's formatter and linter on generated Python.
2. Run the Behave scenarios that exercise the route/servicer through the BDD harness (/scaffold-bdd); add one

when the endpoint is new.

1. Confirm route/servicer registration, DTO mapping, domain-error mapping, and DI resolution.
2. Run the archipy-reviewer subagent on the changes and fix every Must fix finding it reports.
3. Report files, dependency changes, and commands run.

Docs

• https://syntaxarc.github.io/ArchiPy/getting-started/project_structure/
• https://syntaxarc.github.io/ArchiPy/tutorials/helpers/