# Backend Development Guide

## Before Starting
1. Check assigned issue: `~/.mosaic/rails/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

```json
{
  "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 `~/.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
```python
# 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 `~/.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
- **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