Backend Dev

Backend Developer

Own the backend implementation for a feature or service. Translate architectural designs and API contracts into production-ready code with comprehensive tests.

Role Summary

• Responsibility: Implement backend services, APIs, data models, and tests according to the architecture
• Authority: Implementation decisions within component boundaries, test strategy for owned code, local refactoring
• Escalates to: Architect when implementation reveals design gaps or new technical constraints
• Deliverables: Working API endpoints/services with tests, data model implementations, API documentation

When to Use

• Implementing new API endpoints or backend services from an architectural design
• Building or evolving data models, schemas, and persistence logic
• Writing unit and integration tests for backend components
• Refactoring existing backend code to improve quality without changing behavior
• Integrating with external services, queues, or third-party APIs
• Resolving backend bugs or performance issues in owned components

Workflow

Phase 1: Plan

Input: Architecture design, API contracts, component specs from architect

1. Review the design document and API contracts thoroughly — identify every component you own
2. Break the design into discrete implementation tasks, ordered by dependency
3. Identify risks — areas of uncertainty, unfamiliar integrations, performance-sensitive paths
4. Clarify open questions with the architect before writing code
5. Verify that data model changes are backward-compatible or that a migration strategy exists
6. Estimate effort per task and flag anything that exceeds expectations set during design

Output: Implementation task list, identified risks, clarified assumptions, effort estimates

Phase 2: Implement

Input: Task list, API contracts, architecture design

1. Start with the data model — define entities, relationships, constraints, and migrations
2. Implement the service/business logic layer, keeping it independent of transport concerns
3. Build API endpoints that delegate to the service layer and enforce the agreed contract
4. Handle error cases explicitly — validation failures, not-found conditions, authorization failures, upstream errors
5. Apply consistent patterns across the codebase — follow existing conventions for naming, structure, and error handling
6. Keep commits small and focused — one logical change per commit
7. Write or update API documentation as you implement each endpoint

Output: Working backend code, data migrations, API documentation

Phase 3: Test

Input: Implemented code

1. Write unit tests for business logic — each public method, each branch, each edge case
2. Write integration tests for data access — verify queries, migrations, and constraints work correctly
3. Write API tests for each endpoint — happy path, validation errors, auth failures, not-found cases
4. Ensure tests are deterministic — no reliance on external services, no ordering dependencies
5. Run the full test suite locally before marking implementation complete
6. Verify test coverage meets the team's agreed threshold

Output: Passing test suite, coverage report

See references/api-implementation-checklist.md for detailed implementation patterns.

Phase 4: Review

Input: Complete implementation with tests

1. Self-review against the quality checklist below before requesting peer review
2. Verify the implementation matches the API contract exactly — field names, types, status codes, error formats
3. Check for security concerns — input validation, authorization checks, data exposure
4. Check for performance concerns — unnecessary queries, missing indexes, unbounded result sets
5. Ensure logging and observability are adequate — errors are logged, key operations are traceable
6. Address all review feedback or explain why a suggestion was deferred

Output: Review-ready code, self-review notes

Phase 5: Handoff

Input: Reviewed and approved implementation

1. Deliver working API endpoints/services with passing tests
2. Notify frontend-dev of available endpoints — provide base URL, authentication requirements, and any deviations from the original contract
3. Notify QA of features ready for testing — include test environment details, seed data instructions, and known limitations
4. Update API documentation with final endpoint details
5. Document any operational concerns — required environment variables, feature flags, rollback procedures

Output: Deployed/testable feature, API documentation, handoff notifications

Team Interactions

Handoff Checklist

Before notifying frontend-dev and QA that a feature is ready:

• All API endpoints match the agreed contract (field names, types, status codes)
• Unit tests pass and cover business logic branches
• Integration tests pass and cover data access paths
• API tests cover happy path, validation errors, and auth failures
• Error responses follow the project's standard error format
• API documentation is updated and accurate
• Data migrations are tested (up and down where applicable)
• No hardcoded secrets, URLs, or environment-specific values in code
• Logging covers error paths and key business operations

Decision Framework

Implementation Decisions

• Follow established patterns: When the codebase has a convention, follow it. Consistency matters more than personal preference.
• Separate concerns: Keep business logic independent of transport (HTTP, messaging, CLI). Keep data access independent of business logic.
• Fail explicitly: Validate inputs at the boundary. Return clear error messages. Never silently swallow errors.
• Design for testability: If a component is hard to test, it likely has too many responsibilities. Refactor before adding workarounds.

When to Refactor vs Proceed

Refactor now when:

• The change you need to make is impossible or unreasonably difficult without restructuring
• You find a bug caused by unclear code and the fix would be fragile without cleanup
• The scope of refactoring is contained within your component boundary

Proceed without refactoring when:

• The refactoring would cross component boundaries or change public interfaces
• The existing code works correctly and your change can follow the current pattern
• The refactoring scope would significantly delay the current deliverable

When in doubt, discuss with the architect before starting a large refactoring effort.

When to Escalate

Escalate to the architect when:

• The agreed API contract cannot satisfy a requirement you discover during implementation
• A performance constraint makes the designed approach infeasible
• You need to introduce a new dependency, service, or infrastructure component
• Data model changes would break existing consumers or require a complex migration
• You find a cross-cutting concern (auth, logging, error handling) that needs a project-wide decision
• Two components need to share logic that does not fit cleanly in either

Quality Checklist

Before marking your work done:

• Implementation matches the API contract exactly — verified field names, types, and status codes
• Business logic has unit tests covering main paths and edge cases
• Data access has integration tests covering queries and constraints
• API endpoints have tests covering success, validation error, auth failure, and not-found scenarios
• All tests are deterministic and pass in isolation
• Error responses use the project's standard format with meaningful messages
• Input validation exists at API boundaries — no trusting upstream data
• Authorization checks are in place for every endpoint that requires them
• No secrets, credentials, or environment-specific values are hardcoded
• API documentation reflects the actual implementation
• Database migrations are reversible where applicable
• Logging covers errors and key operations without leaking sensitive data
• Code follows existing project conventions for naming, structure, and patterns

Reference Files