Scaffold Logic

---
name: scaffold-logic
description: >-
  Scaffold an ArchiPy logic (use case) under logics/{domain}/ with a unit-of-work
  decorator and DTO I/O. Use for "add business logic", "new use case", "transactional
  operation", or "service layer method".
---

# Scaffold ArchiPy Logic

## 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-logics.mdc`
- `../../rules/using-archipy-models.mdc`

## Before writing files

1. Inspect the target domain's DTOs, repository contract, neighboring logics, DI wiring, and tests.
2. Infer naming and sync/async style from existing code and installed extras.
3. Ask only for an unresolved domain/use-case name or transaction choice. Default to sync for
   `postgres` + `sqlalchemy` and async for `postgres` + `sqlalchemy-async`. Skip a UoW decorator when the
   use-case does not own a SQLAlchemy session.
4. Preserve existing use cases; do not overwrite logic or DTO files.

## Prefer ArchiPy

Install a SQLAlchemy extra only when this use-case owns a Postgres UoW:

```bash
uv add "archipy[postgres,sqlalchemy]"
# or: uv add "archipy[postgres,sqlalchemy-async]"
```

Skip this for Redis/Kafka/other logics that do not wrap a SQLAlchemy session.

## Generate

```text
logics/<domain>/
└── <name>_logic.py
```

Stub shape:

- Google-style class/method docstrings; double quotes; `X | Y` typing.
- Constructor injects the domain repository (or port) — do not construct adapters.
- Public method: domain `*InputDTO` in → domain `*OutputDTO` out.
- Decorate with `postgres_sqlalchemy_atomic_decorator` or `async_postgres_sqlalchemy_atomic_decorator`
  **when Postgres SQLAlchemy is in play**. Otherwise omit the UoW decorator.

```python
from archipy.helpers.decorators.sqlalchemy_atomic import postgres_sqlalchemy_atomic_decorator


class UserRegistrationLogic:
    """Handles user registration within a single database transaction."""

    def __init__(self, user_repository: UserRepository) -> None:
        self._user_repository = user_repository

    @postgres_sqlalchemy_atomic_decorator
    def register_user(self, input_dto: UserRegistrationInputDTO) -> UserRegistrationOutputDTO:
        """Validate and create a user.

        Args:
            input_dto: Registration data from the service layer.

        Returns:
            Output DTO for the newly created user.
        """
        ...
```

If domain DTOs or errors are missing, follow `../scaffold-models/SKILL.md` — do not invent naming.

## Do not

- No FastAPI / gRPC imports.
- May call other domain logics; **never** another domain’s repository.
- No atomic / UoW decorators on repositories or services — only logics.
- Wire via DI in `configs/containers.py`.
- No FastAPI / gRPC imports in logics.

## Verify

1. Run the repository's formatter and linter on generated Python.
2. Add or run Behave scenarios through the service endpoint that calls this logic (success, business-rule failure,
   rollback), with its `@needs-*` containers; if no endpoint exists yet, note that the scenario lands with the service.
3. Confirm DTO boundaries, repository injection, decorator choice, and DI wiring.
4. Run the `archipy-reviewer` subagent on the changes and fix every **Must fix** finding it reports.
5. Report files and commands run.

## Docs

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