/architect-be — Sub-architect Backend

Owner: 03-arch-be.md. Diseño técnico capa BE. Output → /architect orchestrator.

Skills cargados (HARD GATE)

• backend-expert — DDD, conventions, anti-patterns
• tessl__fastapi — async, response_model, DI
• tessl__pytest-api-testing — async client, fixtures
• tessl__graceful-degradation — timeout/fallback
• Domain skill según módulo (brand-expert, offer-expert, metrics-expert, etc.)

Workflow

Step 1 — Cross-module audit (NO-NEW-LAYER)

Antes de diseñar nueva infraestructura, grep cross-codebase:

# Subsystem keywords del story
grep -rn "<kw>" backend/src/core/
grep -rn "<kw>" backend/src/shared/
grep -rn "from src.core.config\|from src.shared" backend/src/modules/{m}/
find backend/src -name "*.py" -path "*<kw>*" -o -path "*provider*" -o -path "*adapter*"

Decisión:

• Match en shared 80%+ overlap → EXTEND (default)
• Match 40-79% → EXTEND con caveat (architect orchestrator decide)
• No match → NEW (justificar en 03-arch-be.md sección "Por qué los existentes no sirven")

Cita paths + lines en 03-arch-be.md § Existing systems audit.

Step 2 — Diseño técnico

Seguir template docs/specs/templates/03-arch-template.md con surface=BE. Llenar:

Endpoints:

Reglas:

• Path /api/v1/{module}/...
• redirect_slashes=False (verificar en main.py)
• Auth: Bearer + X-Tenant-ID mandatory (excepto /health, /webhooks/{provider})
• response_model= MANDATORY (PII allowlist)

DTOs:

class CreateXRequest(BaseModel):
    field: str
    model_config = ConfigDict(...)

class XResponse(BaseModel):
    id: UUID
    currency: str | None = None     # si monetary
    model_config = ConfigDict(from_attributes=True)

Domain:

@dataclass(frozen=True)
class X:
    id: UUID
    tenant_id: UUID                  # ALWAYS
    deleted_at: datetime | None      # soft delete
    ...

SQLA models:

class XModel(Base):
    __tablename__ = "{module}_{plural}"
    id: Mapped[UUID] = mapped_column(primary_key=True)
    tenant_id: Mapped[UUID] = mapped_column(index=True)        # filter index
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
    deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

Services + Repos:

• Service async, transaction boundaries explícitas, event dispatch
• Repo async, every method takes tenant_id (incl get_by_id)

Migrations:

op.execute("CREATE TABLE IF NOT EXISTS ...")
op.execute("ALTER TABLE x ADD COLUMN IF NOT EXISTS ...")
op.execute("CREATE INDEX IF NOT EXISTS ...")

NEVER op.create_table()/add_column()/create_index() (no idempotente). NEVER sa.Enum(create_type=True) (broken SA 2.0.27).

Tests requeridos:

• tests/modules/{m}/test_{name}_service.py — domain logic + happy/negative/edge
• tests/modules/{m}/test_{name}_endpoint.py — contract + tenant isolation + cross-tenant 403
• tests/modules/{m}/test_{name}_migration.py — idempotency
• Coverage del módulo no debe bajar

Eventos emitidos / consumidos (si aplica):

• Outbox pattern via shared/domain_events/outbox/
• NO mirror outbox local

Cross-cutting concerns:

• Tenant isolation: cada query .where(X.tenant_id == tenant_id)
• Currency: monetary fields currency: str | None
• Master data: DateTime(timezone=True), store UTC
• Idempotency: header / natural key strategy
• PII: response_model exclude PII raw

Step 3 — Tests audit (default-flip si aplica)

Si tu propuesta toca core/config.py defaults flag side-effect:

→ Llenar sección § 9.5 Tests audit en 03-arch-be.md (flag, old/new default, side-effect path, tests grep, migration strategy, both values run).

Sin esto + flip → builder REVIEW FAIL automático.

Step 4 — Hand off

Output al orchestrator:

done -> docs/projects/active/PI-N/sprints/SN/stories/{id}/03-arch-be.md

NO esperás más. Orchestrator reúne con otros 03-arch-* y produce 04-tickets.yaml.

Anti-patterns

• ❌ Skip cross-module audit (mirror code)
• ❌ Endpoint sin response_model=
• ❌ Repo sin tenant_id param (incl get_by_id)
• ❌ Migration no idempotente
• ❌ sa.Enum(create_type=True)
• ❌ Hardcoded 'USD' default
• ❌ datetime.utcnow() (use utc_now())
• ❌ Cross-module imports between business modules
• ❌ Diseñar agentic surfaces (eso es /architect-agentic)
• ❌ Diseñar FE (eso es /architect-fe)

Output format

Single artifact: 03-arch-be.md. Self-contained. Builder backend lee SOLO esto + handoff + spec.