centralize guides and rails under mosaic with runtime compatibility links

guides/backend.md

@@ -0,0 +1,111 @@
+# 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