BPM Backend Guardrails

1. Inspect the local codebase first. Inspect the affected module, src/bpm_platform/bootstrap/module_registry.py, relevant entrypoints, tests, and migration trees before proposing code.
2. Decide the ownership boundary. Decide whether the change belongs to an existing module or a new module, and whether the data belongs to control_db, tenant_db, or both.
3. Ask concise questions when critical context is missing. Do not invent sensitive business rules, persistence rules, or cross-module contracts.
4. Keep each concern in the correct layer. Put business logic in application and domain, framework edges in interfaces, and data access in infrastructure.
5. Reject shortcuts that break architecture or scalability. Explain why the shortcut is wrong here, name the risk, and propose the compatible alternative.
6. Verify before claiming success. Run the relevant tests and migration commands, or say exactly what could not be verified and why.

Mandatory Questions / Preguntas Obligatorias

Ask these only when the answer cannot be inferred safely from local context:

• Does this belong to an existing module or require a new module?
• Does the data belong to control_db, tenant_db, or both?
• What is the exact business rule and which invalid cases must be rejected?
• Who consumes this change: HTTP, CLI, worker, scheduler, or another use case?
• Does the change require a schema migration?
• Which other modules or contracts are expected to interact with this change?

Non-Negotiable Rules / Reglas No Negociables

Layers / Capas

• domain must not import FastAPI, SQLAlchemy, JWT libraries, request objects, response objects, or transport concerns.
• application orchestrates use cases and depends on domain plus explicit ports, not concrete infrastructure.
• infrastructure owns ORM models, repositories, SQL, and external adapters.
• interfaces/http owns request schemas, response schemas, routers, and wiring.
• entrypoints assemble runtime processes only.
• bootstrap registers modules and composition.
• platform is only for truly cross-cutting concerns.

Module Boundaries / Limites de Modulo

• Each module must have one clear purpose.
• domain and application must not import another module's infrastructure.
• Cross-module collaboration must happen through explicit orchestration or contracts.
• ORM models stay private to infrastructure and must not leak into API responses or domain logic.

Database Boundaries / Limites de Base de Datos

• control_db and tenant_db are separate boundaries.
• Distributed transactions across them are forbidden.
• Tenant resolution must stay centralized.
• Do not mix tenant functional data into the control plane without explicit architectural justification.

Scalability Rules / Reglas de Escalabilidad

• Query only the rows and columns needed for the use case.
• Push filtering, ordering, limits, pagination, and locking into SQL when they belong there.
• For lookup-by-id flows, use a selective repository query such as session.get(...) or select(...).where(...).
• Never load an entire dataset and filter it in Python for a request-specific lookup.
• Avoid SELECT * when only part of the row is required.
• Avoid N+1 query patterns and unbounded list reads.
• Shape repository methods around real access patterns instead of exposing get_all() and filtering later.

Good Practice Rules / Reglas de Buenas Practicas

Python

• Prefer clear, typed, small units with obvious ownership.
• Avoid giant services.py, helpers.py, or utils.py files with mixed responsibilities.
• Keep error handling explicit and close to the boundary that owns the error mapping.

FastAPI

• Keep routers thin.
• Keep dependencies thin.
• Do not hide business logic in FastAPI dependencies.
• Use request and response schemas deliberately instead of exposing internal models.

SQLAlchemy and SQL

• Put query logic in repositories or infrastructure adapters, not routers.
• Use selective predicates in the database instead of filtering in memory.
• Use existence checks, limits, and ordering intentionally.
• Treat query shape as a scalability concern, not just a persistence detail.

Rejection Behavior / Comportamiento de Rechazo

When the user asks for an architecture-breaking or non-scalable shortcut:

1. Reject the specific approach clearly.
2. Explain why it is incorrect in this repository.
3. Name the actual risk. Examples: coupling, tenancy leakage, inconsistent validation, unbounded memory use, poor query performance, broken transaction boundaries, or hidden side effects.
4. Propose the compatible alternative.
5. Ask a focused follow-up question if the business requirement is still unclear.

Common Rejections / Rechazos Comunes

• "Put the logic in the router." Reject it. Move the business logic to a use case and keep the router as a transport adapter.
• "Fetch everything and find the row by id in memory." Reject it. Put a selective query in the repository layer so the database does the filtering.
• "Return the ORM model directly from the API." Reject it. Map it to a response schema.
• "Skip tests because the change is small." Reject it. Run the minimum relevant verification for the surface you changed.

Repo-Specific Expectations / Expectativas del Repositorio

• Follow the patterns already present in src/bpm_platform/modules/identity, src/bpm_platform/modules/jobs, and src/bpm_platform/modules/audit.
• Register HTTP routers through src/bpm_platform/bootstrap/module_registry.py.
• Keep request-scoped dependency composition aligned with src/bpm_platform/entrypoints/api/dependencies.py and module-level interfaces/http/wiring.py.
• Keep architecture tests green, especially tests/architecture/test_layer_dependencies.py and tests/architecture/test_module_isolation.py.

Use Other Skills When Applicable / Usa Otros Skills Cuando Aplique

• Use brainstorming before creative or behavior-changing work when the repo workflow requires design first.
• Use test-driven-development before feature or bugfix implementation when applicable.
• Use systematic-debugging when dealing with bugs, failures, or unexpected behavior.
• Use verification-before-completion before claiming the work is complete.

Definition of Done / Definicion de Terminado

Do not call a backend change done until all of these are true:

• The code lives in the correct module and layer.
• The architecture and database boundaries are still respected.
• Required wiring, bootstrap registration, and migrations are in place.
• Relevant tests were added or updated.
• Relevant verification was executed, or the exact verification gap was stated explicitly.
• No rejected anti-pattern remains in the final solution.