Scaffold Service

---
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-utils.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

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

## Generate

```text
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.
- Paths follow the REST resource rule in `using-archipy-services.mdc`: `/api/v1/users/{user_uuid}/campaigns/{campaign_uuid}/...`
  — kebab-case literal segments, plural collections, `UUID`-typed `snake_case` path params, `APIRouter(prefix="/api/v1")`.
- JWT auth (Keycloak or other): compute `actor_uuid` = actor (`current_actor.id` / `act`) first, else token subject (`user_id` / `sub`); pass it in the
  input DTO for `created_by*`/`updated_by*`. Never use a path owner uuid (customer, merchant, admin, user…) as the actor (see `using-archipy-services.mdc`).
- 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.
- Request/response DTOs extend `BaseProtobufDTO` (`_proto_class`, `from_proto` / `to_proto`); `from_proto` is the
  validation boundary. Catch `ValidationError` and raise `InvalidArgumentError ... from e`; keep proto types out of
  logics. See `rules/using-archipy-models.mdc`.

## Bootstrap (entrypoint)

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

```python
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.
3. Confirm route/servicer registration, DTO mapping, domain-error mapping, and DI resolution.
4. Run the `archipy-reviewer` subagent on the changes and fix every **Must fix** finding it reports.
5. Report files, dependency changes, and commands run.

## Docs

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