stack/guides/BACKEND.md

Backend Development Guide

Before Starting

1. Check assigned issue: ~/.config/mosaic/tools/git/issue-list.sh -a @me
2. Create scratchpad: docs/scratchpads/{issue-number}-{short-name}.md
3. Review API contracts and database schema

Development Standards

API Design

• Follow RESTful conventions (or GraphQL patterns if applicable)
• Use consistent endpoint naming: /api/v1/resource-name
• Return appropriate HTTP status codes
• Include pagination for list endpoints
• Document all endpoints (OpenAPI/Swagger preferred)

Database

• Write migrations for schema changes
• Use parameterized queries (prevent SQL injection)
• Index frequently queried columns
• Document relationships and constraints

Error Handling

• Return structured error responses
• Log errors with context (request ID, user ID if applicable)
• Never expose internal errors to clients
• Use appropriate error codes

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "User-friendly message",
    "details": []
  }
}

Security

• Validate all input at API boundaries
• Implement rate limiting on public endpoints
• Use secrets from Vault (see docs/vault-secrets-structure.md)
• Never log sensitive data (passwords, tokens, PII)
• Follow OWASP guidelines

Authentication/Authorization

• Use project's established auth pattern
• Validate tokens on every request
• Check permissions before operations
• See ~/.config/mosaic/guides/AUTHENTICATION.md for details

Testing Requirements (TDD)

1. Write tests BEFORE implementation
2. Minimum 85% coverage
3. Test categories:
   • Unit tests for business logic
   • Integration tests for API endpoints
   • Database tests with transactions/rollback

Test Patterns

# API test example structure
class TestResourceEndpoint:
    def test_create_returns_201(self):
        pass
    def test_create_validates_input(self):
        pass
    def test_get_returns_404_for_missing(self):
        pass
    def test_requires_authentication(self):
        pass

Code Style

• Follow Google Style Guide for your language
• TypeScript: Follow ~/.config/mosaic/guides/TYPESCRIPT.md — MANDATORY
• Use linter/formatter from project configuration
• Keep functions focused and small
• Document complex business logic

TypeScript Quick Rules (see TYPESCRIPT.md for full guide)

• NO any — define explicit types always
• NO lazy unknown — only for error catches and external data with validation
• Explicit return types on all exported functions
• Explicit parameter types always
• DTO files are REQUIRED for module/API boundaries (*.dto.ts)
• Interface for DTOs — never inline object types
• Typed errors — use custom error classes

Performance

• Use database connection pooling
• Implement caching where appropriate
• Profile slow endpoints
• Use async operations for I/O

Commit Format

feat(#45): Add user registration endpoint

- POST /api/v1/users for registration
- Email validation and uniqueness check
- Password hashing with bcrypt

Fixes #45

Before Completing

1. Run full test suite
2. Verify migrations work (up and down)
3. Test API with curl/httpie
4. Update scratchpad with completion notes
5. Reference issue in commit