scaffold-models

Files (1)

• SKILL.md

SKILL.md (first lines)

# Scaffold ArchiPy Models

## Scope

**Only** `models/`. Do not create repositories, logics, services, or helpers here.

## Read first

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

- `../../rules/using-archipy-models.mdc`
- `../../rules/architecture-for-apps.mdc`
- `../../rules/using-archipy-utils.mdc`

## Before writing files

1. Inspect existing `models/` (DTOs, errors, entities, types), neighboring domains, and the installed ArchiPy version.
2. Infer domain name, DTO naming, and error grouping from existing modules.
3. Ask only for unresolved domain / operation names.
4. Preserve existing model modules; do not overwrite.

## Generate

```text
models/
├── dtos/<domain>/
│   ├── domain/v{n}/
│   │   ├── <op>_input_dto.py
│   │   └── <op>_output_dto.py
│   └── repository/
│       ├── <action>_command_dto.py
│       └── <action>_query_dto.py
├── errors/
│   └── <domain>_errors.py
├── entities/                    # optional
│   └── <domain>_entity.py
└── types/                       # optional
    └── <domain>_types.py
```

Naming: `*InputDTO` / `*OutputDTO` for domain (versioned under `domain/v{n}/`); `*CommandDTO` / `*QueryDTO` /
`*ResponseDTO` for repository (never versioned). Any repository method with two or more parameters takes a single
`*CommandDTO` (write) / `*QueryDTO` (read) instead of positional arguments. Entities/DTOs for JWT-authenticated writes carry an explicit `actor_uuid` that fills `created_by*`/`updated_by*`
(actor from `current_actor`/`act` first, token `user_id`/`sub` second; never a path owner uuid).
Prefer ArchiPy `BaseDTO` and the exported `BaseError` hierarchy.
Verify imports against the app's installed ArchiPy version before writing.

Example shapes (`order` → rename):

```python
# models/dtos/order/domain/v1/order_create_input_dto.py
from pydantic import Field, PositiveInt

from archipy.models.dtos.base_dtos import BaseDTO


class OrderCreateInputDTO(BaseDTO):
    """Domain input crossing the service → logic boundary."""

    customer_id: str = Field(min_length=1)
    sku: str = Field(min_length=1)
    quantity: PositiveInt
```

```python
# models/dtos/order/domain/v1/order_create_output_dto.py
from archipy.models.dtos.base_dtos import BaseDTO


class OrderCreateOutputDTO(BaseDTO):
    """Domain output returned to the service layer."""

    order_id: str
    status: str
```

```python
# models/dtos/order/repository/order_create_command_dto.py
from pydantic import PositiveInt

from archipy.models.dtos.base_dtos import BaseDTO


class OrderCreateCommandDTO(BaseDTO):
    """Repository write command — mapped from domain input inside the logic."""

    customer_id: str
    sku: str
    quantity: PositiveInt
```

```python
# models/errors/order_errors.py
from archipy.models.errors import InvalidArgumentError, NotFoundError


class OrderNotFoundError(NotFoundError):
    """Raised when an order cannot be located."""


class OrderInvalidArgumentError(InvalidArgumentError):
    """Raised when order input fails domain validation."""
```

Prefer Pydantic's constrained types over `int = Field(gt=0)` / bare `str`: `PositiveInt`, `NonNegativeInt`,
`NonNegativeFloat`, `SecretStr` (tokens, passwords, API keys — never log or serialize the raw value), `HttpUrl`,
`EmailStr`, `UUID4`, `StringConstraints`, and the specific date/time types: `NaiveDatetime` (default for
timestamps; no timezone-aware fields), `PastDatetime`, `FutureDatetime`, `PastDate`, `FutureDate` — never bare `datetime` / `date`
when a stricter type fits. Reach for `pydantic-extra-types` (`PhoneNumber`,
`Country`, `Currency`, `Coordinate`, …) before hand-rolled validators; add it to the app's dependencies first. Read raw
secrets only at the boundary with `.get_secret_value()`. Reference: https://docs.pydantic.dev/latest/api/types/

Make DTOs reject invalid states at construction so downstream code and tests only see valid inputs: use
`@field_validator` for single-field rules and `@model_validator(mode="after")` for cross-field rules (ranges,
exactly-one-of, conditionally required fields). Prefer a type over a validator, and a discriminated union /
`Literal` / `StrEnum` over optional fields plus runtime `if`s. Validators are pure (no I/O; uniqueness and existence
checks stay in logics). Cover each validator with one invalid example at the DTO boundary.

For gRPC payloads extend `BaseProtobufDTO` instead of `BaseDTO` and set `_proto_class`. Unset proto3 scalars arrive

From SyntaxArc/archipy-plugin, MIT.

More from SyntaxArc/archipy-plugin