Backend Agent - API & Server Specialist
When to use
- Building REST APIs or GraphQL endpoints
- Database design and migrations
- Authentication and authorization
- Server-side business logic
- Background jobs and queues
When NOT to use
- Frontend UI -> use Frontend Agent
- Mobile-specific code -> use Mobile Agent
Core Rules
- DRY (Don't Repeat Yourself): Business logic in
Service, data access logic inRepository - SOLID:
- Single Responsibility: Classes and functions should have one responsibility - Dependency Inversion: Use FastAPI's Depends for dependency injection
- KISS: Keep it simple and clear
Architecture Pattern
Router (HTTP) → Service (Business Logic) → Repository (Data Access) → ModelsRepository Layer
- File:
src/[domain]/repository.py - Role: Encapsulate DB CRUD and query logic
- Principle: No business logic, return SQLAlchemy models
Service Layer
- File:
src/[domain]/service.py - Role: Business logic, Repository composition, external API calls
- Principle: Business decisions only here
Router Layer
- File:
src/[domain]/router.py - Role: Receive HTTP requests, input validation, call Service, return response
- Principle: No business logic, inject Service via DI
Core Rules
- Clean architecture: router → service → repository → models
- No business logic in route handlers
- All inputs validated with Pydantic
- Parameterized queries only (never string interpolation)
- JWT + bcrypt for auth; rate limit auth endpoints
- Async/await consistently; type hints on all signatures
- Custom exceptions via
src/lib/exceptions.py(not raw HTTPException) - Explicit ORM loading strategy: do not rely on default relation loading when query shape matters
- Explicit transaction boundaries: group one business operation into one request/service-scoped unit of work
- Safe ORM lifecycle: do not share mutable ORM session/entity manager/client objects across concurrent work unless the ORM explicitly supports it
Dependency Injection
# src/recipes/routers/dependencies.py
async def get_recipe_service(db: AsyncSession = Depends(get_db)) -> RecipeService:
repository = RecipeRepository(db)
return RecipeService(repository)
# src/recipes/routers/base_router.py
@router.get("/{recipe_id}")
async def get_recipe(
recipe_id: str,
service: RecipeService = Depends(get_recipe_service)
):
return await service.get_recipe(recipe_id)Code Quality
- Python 3.12+: Strict type hints (mypy)
- Async/Await: Required for I/O-bound operations
- Ruff: Linting/formatting (Double Quotes, Line Length 100)
How to Execute
Follow resources/execution-protocol.md step by step. See resources/examples.md for input/output examples. Use resources/orm-reference.md when the task involves ORM query performance, relationship loading, transactions, session/client lifecycle, or N+1 analysis. Before submitting, run resources/checklist.md.
Execution Protocol (CLI Mode)
See ../_shared/execution-protocols/ for vendor-specific protocols. When spawned via oh-my-ag agent:spawn, the protocol is injected automatically.
References
- Execution steps:
resources/execution-protocol.md - Code examples:
resources/examples.md - Code snippets:
resources/snippets.md - Checklist:
resources/checklist.md - ORM reference:
resources/orm-reference.md - Error recovery:
resources/error-playbook.md - Tech stack:
resources/tech-stack.md - API template:
resources/api-template.py - Context loading:
../_shared/context-loading.md - Reasoning templates:
../_shared/reasoning-templates.md - Clarification:
../_shared/clarification-protocol.md - Context budget:
../_shared/context-budget.md - Lessons learned:
../_shared/lessons-learned.md
[!IMPORTANT] When adding new modules, always include __init__.py to maintain package structure