10689a30d2
Work packages completed: - WP1: packages/forge — pipeline runner, stage adapter, board tasks, brief classifier, persona loader with project-level overrides. 89 tests, 95.62% coverage. - WP2: packages/macp — credential resolver, gate runner, event emitter, protocol types. 65 tests, 96.24% coverage. Full Python-to-TS port preserving all behavior. - WP3: plugins/mosaic-framework — OC rails injection plugin (before_agent_start + subagent_spawning hooks for Mosaic contract enforcement). - WP4: profiles/ (domains, tech-stacks, workflows), guides/ (17 docs), skills/ (5 universal skills), forge pipeline assets (48 markdown files). Board deliberation: docs/reviews/consolidation-board-memo.md Brief: briefs/monorepo-consolidation.md Consolidates mosaic/stack (forge, MACP, bootstrap framework) into mosaic/mosaic-stack. 154 new tests total. Zero Python — all TypeScript/ESM.
126 lines
3.2 KiB
Markdown
126 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```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 `~/.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
|
|
|
|
```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 `~/.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
|