new-feature

new-feature

Do not open any file for editing until all 5 steps below are completed.

---

Step 1 — Define the API contract

Write the contract in plain text before any code. Answer these 4 questions:

Endpoint:   POST /generate/image
Request:    { prompt: str, model_id: str, width: int, height: int }
Response:   { task_id: str, status: "queued" }
Side effect: creates a task, holds credits

If you cannot answer all 4 in 2 sentences, the feature scope is unclear. Stop and clarify with the user.

---

Step 2 — Identify layers touched

Use this decision matrix to know which files you will create or modify:

What the feature needs	Layers touched	Files
New HTTP endpoint only	Router	routers/<domain>.py
Endpoint + business logic	Router + Service	+ services/<domain>/
Logic + database	Router + Service + Repo	+ repositories/protocols.py, repositories/sqlalchemy/<domain>.py
Logic + external API	Router + Service + Provider	+ providers/<name>.py
Logic + credits charge	All of the above + Credits	+ services/credits/user.py (read-only — single writer!)

Write the list: "This feature touches: Router, Service, Repo."

Do not touch more layers than listed. If you discover you need more, stop and re-plan.

---

Step 3 — Define the test scenario

Write the test scenario before code. Two scenarios minimum:

# Scenario 1: happy path
# Given: user has 10.00 credits, valid prompt
# When:  POST /generate/image with correct payload
# Then:  202 response, task_id returned, credits held

# Scenario 2: edge case
# Given: user has 0.00 credits
# When:  POST /generate/image
# Then:  402 response, no task created, no credits touched

These become your actual pytest tests in tests/unit/ or tests/integration/.

---

Step 4 — Build bottom-up

Always build in this order. Never start from the router.

1. Repository (if new data access needed)
   └── Add method to CreditsRepoProtocol
   └── Implement in SQLAlchemyCreditsRepo
   └── Implement in FakeCreditsRepo (tests/conftest.py)

2. Service
   └── Accepts repo via Protocol (never imports SQLAlchemy)
   └── Contains all business logic
   └── Raises domain exceptions (ValueError, not HTTPException)

3. Router
   └── Thin: validate schema → call service → return response
   └── Maps domain exceptions to HTTP codes
   └── No logic beyond 10 lines per endpoint handler

4. Schema
   └── Request and response Pydantic models
   └── Goes in schemas/<domain>.py, never inside routers/