From a6e21d793b7a3ab00c986b92acd1e4c15825d9e0 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Thu, 5 Feb 2026 06:04:16 +0200 Subject: [PATCH] chore: add epic specs and clean up internal files - Add epic-02 (Core NestJS Compatibility) spec - Add epic-03 (Performance Benchmarks) spec - Move specs from .cursor/specs to docs/specs - Add .plans/ and .cursor/ to .gitignore - Remove internal planning files from git tracking Co-authored-by: Cursor --- .cursor/specs/epic-01-examples-enhancement.md | 210 --- .gitignore | 4 + .plans/dependency-graph.md | 172 -- .plans/epics.json | 44 - .plans/stories.json | 271 --- .plans/tasks.json | 1671 ----------------- docs/specs/epic-02-core-nest-compatibility.md | 375 ++++ docs/specs/epic-03-performance-benchmarks.md | 527 ++++++ 8 files changed, 906 insertions(+), 2368 deletions(-) delete mode 100644 .cursor/specs/epic-01-examples-enhancement.md delete mode 100644 .plans/dependency-graph.md delete mode 100644 .plans/epics.json delete mode 100644 .plans/stories.json delete mode 100644 .plans/tasks.json create mode 100644 docs/specs/epic-02-core-nest-compatibility.md create mode 100644 docs/specs/epic-03-performance-benchmarks.md diff --git a/.cursor/specs/epic-01-examples-enhancement.md b/.cursor/specs/epic-01-examples-enhancement.md deleted file mode 100644 index e5ced62..0000000 --- a/.cursor/specs/epic-01-examples-enhancement.md +++ /dev/null @@ -1,210 +0,0 @@ -# Epic: Examples & Documentation Enhancement - -## Overview - -Enhance modkit examples to demonstrate all documented patterns and close the gap between documentation and working code. The `hello-mysql` example will be extended with authentication, validation, middleware patterns, and lifecycle management. - -**Goal**: Users should be able to find working example code for every pattern described in the documentation. - -**Success Criteria**: -- All documented patterns have corresponding example code -- Examples are tested and pass CI -- Documentation references point to actual runnable code - ---- - -## Stories - -### Story 1: Authentication Module - -**Description**: Add a complete authentication module to `hello-mysql` demonstrating JWT-based auth, protected routes, and user context extraction. - -**Acceptance Criteria**: -- [ ] JWT middleware extracts and validates tokens -- [ ] Protected routes require valid authentication -- [ ] User info is available in request context -- [ ] Mix of public and authenticated endpoints works -- [ ] Token generation endpoint exists -- [ ] Tests cover auth success and failure cases - -**Documentation Reference**: `docs/guides/authentication.md` - -#### Tasks -- [ ] Create `internal/modules/auth/` module structure -- [ ] Implement JWT middleware with token validation -- [ ] Add typed context helpers for user extraction -- [ ] Create `/auth/login` endpoint for token generation -- [ ] Protect existing `/users` CRUD routes (except GET list) -- [ ] Add auth module tests (unit + integration) -- [ ] Update README with auth usage examples - ---- - -### Story 2: Request Validation - -**Description**: Add structured request validation to `hello-mysql` demonstrating validation patterns with proper error responses. - -**Acceptance Criteria**: -- [ ] Request body validation on POST/PUT endpoints -- [ ] Field-level validation error responses -- [ ] RFC 7807 Problem Details for validation errors -- [ ] Query parameter validation examples -- [ ] Path parameter validation examples - -**Documentation Reference**: `docs/guides/validation.md` - -#### Tasks -- [ ] Add validation helper package in `internal/validation/` -- [ ] Implement field-level validation for CreateUserRequest -- [ ] Implement field-level validation for UpdateUserRequest -- [ ] Add validation error response type (RFC 7807 extension) -- [ ] Add query parameter validation example (list pagination) -- [ ] Add validation tests -- [ ] Document validation patterns in example README - ---- - -### Story 3: Advanced Middleware Patterns - -**Description**: Add examples of common middleware patterns: CORS, rate limiting, and custom middleware as providers. - -**Acceptance Criteria**: -- [ ] CORS middleware configured and working -- [ ] Rate limiting middleware with configurable limits -- [ ] Custom middleware registered as provider -- [ ] Route group with scoped middleware -- [ ] Middleware ordering is demonstrated - -**Documentation Reference**: `docs/guides/middleware.md` - -#### Tasks -- [ ] Add CORS middleware configuration -- [ ] Implement rate limiting middleware using `golang.org/x/time/rate` -- [ ] Create timing/metrics middleware example -- [ ] Add route group example (`/api/v1/` prefix) -- [ ] Register middleware as providers for dependency injection -- [ ] Add middleware tests -- [ ] Document middleware patterns in example README - ---- - -### Story 4: Lifecycle & Cleanup Patterns - -**Description**: Add examples demonstrating proper resource cleanup and graceful shutdown patterns. - -**Acceptance Criteria**: -- [ ] Database connection cleanup on shutdown -- [ ] Graceful shutdown with in-flight request handling -- [ ] Context-based cancellation patterns -- [ ] Resource cleanup order is correct - -**Documentation Reference**: `docs/guides/lifecycle.md` - -#### Tasks -- [ ] Add cleanup interface and implementation to database module -- [ ] Implement graceful shutdown hook in main -- [ ] Add context cancellation example for long-running operations -- [ ] Document cleanup order (LIFO) -- [ ] Add lifecycle tests -- [ ] Update README with lifecycle patterns - ---- - -### Story 5: Route Groups & API Versioning - -**Description**: Demonstrate route grouping patterns for API versioning and scoped middleware. - -**Acceptance Criteria**: -- [ ] API versioning with `/api/v1/` prefix -- [ ] Route groups with shared middleware -- [ ] Nested route groups example -- [ ] Controller uses groups effectively - -**Documentation Reference**: `docs/guides/controllers.md` - -#### Tasks -- [ ] Refactor routes to use `/api/v1/` prefix -- [ ] Add route group with auth middleware -- [ ] Add nested group example (e.g., `/api/v1/admin/`) -- [ ] Update controller to demonstrate grouping -- [ ] Add routing tests for groups -- [ ] Document routing patterns - ---- - -### Story 6: Test Coverage Improvements - -**Description**: Improve test coverage for core modkit library and ensure examples have comprehensive tests. - -**Acceptance Criteria**: -- [ ] `buildVisibility()` has direct unit tests -- [ ] Provider/Controller build errors are tested -- [ ] HTTP middleware edge cases are tested -- [ ] Example tests cover new features -- [ ] CI coverage meets threshold - -**Documentation Reference**: `docs/guides/testing.md` - -#### Tasks -- [ ] Add unit tests for `buildVisibility()` in kernel -- [ ] Add tests for ProviderBuildError scenarios -- [ ] Add tests for ControllerBuildError scenarios -- [ ] Add HTTP middleware error recovery tests -- [ ] Add router edge case tests (conflicts, invalid methods) -- [ ] Ensure all new example features have tests -- [ ] Update testing guide with new patterns - ---- - -### Story 7: Documentation Synchronization - -**Description**: Ensure all documentation guides reference working example code and patterns are consistent. - -**Acceptance Criteria**: -- [ ] All guides reference example code where applicable -- [ ] Code snippets in docs match actual example code -- [ ] No orphaned documentation (patterns without examples) -- [ ] README links are correct - -#### Tasks -- [ ] Audit `docs/guides/authentication.md` vs example code -- [ ] Audit `docs/guides/validation.md` vs example code -- [ ] Audit `docs/guides/middleware.md` vs example code -- [ ] Audit `docs/guides/lifecycle.md` vs example code -- [ ] Update guides with correct code references -- [ ] Add "See example" links to each guide -- [ ] Update main README with feature matrix - ---- - -## Priority Order - -1. **Story 1: Authentication** - Most requested missing feature -2. **Story 2: Validation** - Critical for real-world usage -3. **Story 3: Middleware** - Completes HTTP patterns -4. **Story 4: Lifecycle** - Important for production use -5. **Story 5: Route Groups** - Improves organization -6. **Story 6: Testing** - Quality assurance -7. **Story 7: Documentation** - Final polish - -## Estimated Scope - -- **Total Stories**: 7 -- **Total Tasks**: ~42 -- **Affected Files**: examples/hello-mysql/, modkit/ (tests), docs/guides/ - -## Dependencies - -- Stories 2-5 depend on existing `hello-mysql` structure -- Story 6 depends on Stories 1-5 being complete -- Story 7 depends on all other stories - -## Labels for Issues - -- `epic` - This epic -- `story` - Each story -- `task` - Each task -- `enhancement` - New features -- `documentation` - Doc updates -- `examples` - Example improvements -- `testing` - Test improvements diff --git a/.gitignore b/.gitignore index 50c4e58..63df557 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,7 @@ # Coverage files coverage.out coverage-examples.out + +# Internal planning files +.plans/ +.cursor/ diff --git a/.plans/dependency-graph.md b/.plans/dependency-graph.md deleted file mode 100644 index 467f280..0000000 --- a/.plans/dependency-graph.md +++ /dev/null @@ -1,172 +0,0 @@ -# Dependency Graph - -```mermaid -graph TD - T-001 --> T-002 - T-002 --> T-003 - T-001 --> T-004 - T-002 --> T-004 - T-002 --> T-005 - T-003 --> T-005 - T-001 --> T-006 - T-002 --> T-006 - T-003 --> T-006 - T-004 --> T-006 - T-005 --> T-006 - T-006 --> T-007 - - T-008 --> T-009 - T-008 --> T-010 - T-008 --> T-011 - T-008 --> T-012 - T-011 --> T-012 - T-008 --> T-013 - T-009 --> T-013 - T-010 --> T-013 - T-011 --> T-013 - T-012 --> T-013 - T-013 --> T-014 - - T-015 --> T-019 - T-016 --> T-019 - T-017 --> T-019 - T-015 --> T-020 - T-016 --> T-020 - T-017 --> T-020 - T-018 --> T-020 - T-019 --> T-020 - T-020 --> T-021 - - T-022 --> T-023 - T-023 --> T-024 - T-022 --> T-025 - T-023 --> T-025 - T-022 --> T-026 - T-023 --> T-026 - T-024 --> T-026 - T-026 --> T-027 - - T-018 --> T-028 - T-028 --> T-029 - T-002 --> T-029 - T-028 --> T-030 - T-028 --> T-031 - T-028 --> T-032 - T-029 --> T-032 - T-030 --> T-032 - T-031 --> T-032 - T-032 --> T-033 - - T-007 --> T-034 - T-014 --> T-034 - T-021 --> T-034 - T-027 --> T-034 - T-033 --> T-034 - - T-007 --> T-035 - T-014 --> T-035 - T-021 --> T-035 - T-027 --> T-035 - T-033 --> T-035 - - T-007 --> T-036 - T-014 --> T-036 - T-021 --> T-036 - T-027 --> T-036 - T-033 --> T-036 - - T-007 --> T-037 - T-014 --> T-037 - T-021 --> T-037 - T-027 --> T-037 - T-033 --> T-037 - - T-007 --> T-038 - T-014 --> T-038 - T-021 --> T-038 - T-027 --> T-038 - T-033 --> T-038 - - T-007 --> T-039 - T-014 --> T-039 - T-021 --> T-039 - T-027 --> T-039 - T-033 --> T-039 - - T-039 --> T-040 - T-040 --> T-041 - T-040 --> T-042 - T-040 --> T-043 - T-040 --> T-044 - T-041 --> T-045 - T-042 --> T-045 - T-043 --> T-045 - T-044 --> T-045 - T-045 --> T-046 - T-046 --> T-047 -``` - -Adjacency list (task -> depends_on): - -- T-001 -> [] -- T-002 -> [T-001] -- T-003 -> [T-002] -- T-004 -> [T-001, T-002] -- T-005 -> [T-002, T-003] -- T-006 -> [T-001, T-002, T-003, T-004, T-005] -- T-007 -> [T-006] -- T-008 -> [] -- T-009 -> [T-008] -- T-010 -> [T-008] -- T-011 -> [T-008] -- T-012 -> [T-008, T-011] -- T-013 -> [T-008, T-009, T-010, T-011, T-012] -- T-014 -> [T-013] -- T-015 -> [] -- T-016 -> [] -- T-017 -> [] -- T-018 -> [] -- T-019 -> [T-015, T-016, T-017] -- T-020 -> [T-015, T-016, T-017, T-018, T-019] -- T-021 -> [T-020] -- T-022 -> [] -- T-023 -> [T-022] -- T-024 -> [T-023] -- T-025 -> [T-022, T-023] -- T-026 -> [T-022, T-023, T-024] -- T-027 -> [T-026] -- T-028 -> [T-018] -- T-029 -> [T-028, T-002] -- T-030 -> [T-028] -- T-031 -> [T-028] -- T-032 -> [T-028, T-029, T-030, T-031] -- T-033 -> [T-032] -- T-034 -> [T-007, T-014, T-021, T-027, T-033] -- T-035 -> [T-007, T-014, T-021, T-027, T-033] -- T-036 -> [T-007, T-014, T-021, T-027, T-033] -- T-037 -> [T-007, T-014, T-021, T-027, T-033] -- T-038 -> [T-007, T-014, T-021, T-027, T-033] -- T-039 -> [T-007, T-014, T-021, T-027, T-033] -- T-040 -> [T-039] -- T-041 -> [T-040] -- T-042 -> [T-040] -- T-043 -> [T-040] -- T-044 -> [T-040] -- T-045 -> [T-041, T-042, T-043, T-044] -- T-046 -> [T-045] -- T-047 -> [T-046] - -Execution waves: - -- Wave 1: T-001, T-008, T-015, T-016, T-017, T-018, T-022 -- Wave 2: T-002, T-009, T-010, T-011, T-019, T-023, T-028 -- Wave 3: T-003, T-004, T-012, T-020, T-024, T-025, T-029, T-030, T-031 -- Wave 4: T-005, T-013, T-021, T-026, T-032 -- Wave 5: T-006, T-014, T-027, T-033 -- Wave 6: T-007 -- Wave 7: T-034, T-035, T-036, T-037, T-038, T-039 -- Wave 8: T-040 -- Wave 9: T-041, T-042, T-043, T-044 -- Wave 10: T-045 -- Wave 11: T-046 -- Wave 12: T-047 diff --git a/.plans/epics.json b/.plans/epics.json deleted file mode 100644 index 75a0e65..0000000 --- a/.plans/epics.json +++ /dev/null @@ -1,44 +0,0 @@ -[ - { - "id": "E-PLAN-001", - "title": "Examples and Documentation Enhancement", - "goal": "Every documented modkit pattern has runnable example code in hello-mysql with passing tests and docs that reference the code", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Overview" - }, - "scope": { - "in": [ - "Extend hello-mysql example with auth, validation, middleware, lifecycle, and route grouping patterns", - "Add/expand tests for examples and core modkit library", - "Synchronize guides and README with working example code" - ], - "out": [ - "New production features outside documented patterns", - "Breaking changes to public APIs without documentation updates" - ] - }, - "success_metrics": [ - "All documented patterns have corresponding runnable example code", - "Example and library tests pass in CI", - "Docs reference actual example code paths" - ], - "risks": [ - "Overlap between middleware route groups and API versioning work could cause rework", - "Test additions may be flaky without stable fixtures" - ], - "assumptions": [ - "CI has a standard pull request workflow and runs make test", - "hello-mysql example is the primary target for new patterns" - ], - "story_ids": [ - "ST-001", - "ST-002", - "ST-003", - "ST-004", - "ST-005", - "ST-006", - "ST-007" - ] - } -] diff --git a/.plans/stories.json b/.plans/stories.json deleted file mode 100644 index 2a81bae..0000000 --- a/.plans/stories.json +++ /dev/null @@ -1,271 +0,0 @@ -[ - { - "id": "ST-001", - "epic_id": "E-PLAN-001", - "title": "Authentication Module Example", - "goal": "hello-mysql demonstrates JWT auth with protected routes and tests", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module" - }, - "scope": { - "in": [ - "Auth module with JWT middleware, login endpoint, and route protection", - "Auth-related tests and README updates" - ], - "out": [ - "Alternative auth mechanisms beyond JWT", - "Cross-example auth changes" - ] - }, - "success_metrics": [ - "Auth success and failure tests pass", - "Docs point to working auth example" - ], - "risks": [ - "JWT validation details may differ from guide expectations" - ], - "assumptions": [ - "JWT secret/config can be sourced from example config" - ], - "task_ids": [ - "T-001", - "T-002", - "T-003", - "T-004", - "T-005", - "T-006", - "T-007" - ] - }, - { - "id": "ST-002", - "epic_id": "E-PLAN-001", - "title": "Request Validation Example", - "goal": "hello-mysql demonstrates structured request validation with RFC 7807 errors", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation" - }, - "scope": { - "in": [ - "Validation helpers, request validations, and RFC 7807 error responses", - "Validation tests and README updates" - ], - "out": [ - "Schema generation tooling or external validation frameworks" - ] - }, - "success_metrics": [ - "POST/PUT validations return field-level errors", - "Docs show working validation examples" - ], - "risks": [ - "Validation error format may conflict with existing error responses" - ], - "assumptions": [ - "Example routes already accept CreateUserRequest and UpdateUserRequest" - ], - "task_ids": [ - "T-008", - "T-009", - "T-010", - "T-011", - "T-012", - "T-013", - "T-014" - ] - }, - { - "id": "ST-003", - "epic_id": "E-PLAN-001", - "title": "Advanced Middleware Patterns", - "goal": "hello-mysql demonstrates CORS, rate limiting, and provider-based middleware with tests", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns" - }, - "scope": { - "in": [ - "CORS, rate limiting, timing/metrics middleware", - "Route groups and middleware ordering examples", - "Tests and README updates" - ], - "out": [ - "Production-grade metrics backends" - ] - }, - "success_metrics": [ - "Middleware examples compile and are exercised in tests", - "Docs point to working middleware examples" - ], - "risks": [ - "Rate limiting configuration may be environment-sensitive" - ], - "assumptions": [ - "Middleware can be registered as providers in hello-mysql" - ], - "task_ids": [ - "T-015", - "T-016", - "T-017", - "T-018", - "T-019", - "T-020", - "T-021" - ] - }, - { - "id": "ST-004", - "epic_id": "E-PLAN-001", - "title": "Lifecycle and Cleanup Patterns", - "goal": "hello-mysql demonstrates cleanup and graceful shutdown with tests", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns" - }, - "scope": { - "in": [ - "Database cleanup interface and shutdown hooks", - "Context cancellation examples", - "Lifecycle tests and README updates" - ], - "out": [ - "Production deployment docs" - ] - }, - "success_metrics": [ - "Shutdown behavior is covered by tests", - "Cleanup order is documented" - ], - "risks": [ - "Graceful shutdown tests may require timing tolerances" - ], - "assumptions": [ - "hello-mysql main allows adding shutdown hooks" - ], - "task_ids": [ - "T-022", - "T-023", - "T-024", - "T-025", - "T-026", - "T-027" - ] - }, - { - "id": "ST-005", - "epic_id": "E-PLAN-001", - "title": "Route Groups and API Versioning", - "goal": "hello-mysql demonstrates route grouping, versioning, and scoped middleware", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning" - }, - "scope": { - "in": [ - "Refactor routes under /api/v1 and demonstrate nested groups", - "Routing tests and documentation" - ], - "out": [ - "New API versions beyond v1" - ] - }, - "success_metrics": [ - "Routing tests pass for grouped routes", - "Docs show grouping patterns" - ], - "risks": [ - "Refactor may break existing example references" - ], - "assumptions": [ - "Route refactor can be done without changing business logic" - ], - "task_ids": [ - "T-028", - "T-029", - "T-030", - "T-031", - "T-032", - "T-033" - ] - }, - { - "id": "ST-006", - "epic_id": "E-PLAN-001", - "title": "Test Coverage Improvements", - "goal": "Core library and example coverage increases with new tests", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements" - }, - "scope": { - "in": [ - "Kernel and build error tests", - "HTTP middleware edge case tests", - "Coverage for new example features", - "Testing guide updates" - ], - "out": [ - "Performance benchmarking" - ] - }, - "success_metrics": [ - "CI coverage meets threshold", - "New unit tests for build errors pass" - ], - "risks": [ - "Existing tests may need refactoring to avoid flakiness" - ], - "assumptions": [ - "Coverage threshold is enforced in CI" - ], - "task_ids": [ - "T-034", - "T-035", - "T-036", - "T-037", - "T-038", - "T-039", - "T-040" - ] - }, - { - "id": "ST-007", - "epic_id": "E-PLAN-001", - "title": "Documentation Synchronization", - "goal": "Guides and README point to working example code", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization" - }, - "scope": { - "in": [ - "Audit guides and update references", - "Add example links and feature matrix" - ], - "out": [ - "New documentation topics not in scope" - ] - }, - "success_metrics": [ - "No orphaned doc patterns without examples", - "README links are correct" - ], - "risks": [ - "Docs may drift if example paths change later" - ], - "assumptions": [ - "Guides live under docs/guides/" - ], - "task_ids": [ - "T-041", - "T-042", - "T-043", - "T-044", - "T-045", - "T-046", - "T-047" - ] - } -] diff --git a/.plans/tasks.json b/.plans/tasks.json deleted file mode 100644 index 95ca05f..0000000 --- a/.plans/tasks.json +++ /dev/null @@ -1,1671 +0,0 @@ -[ - { - "id": "T-001", - "story_id": "ST-001", - "title": "Create auth module structure", - "motivation": "Provide a dedicated auth module in hello-mysql to match the authentication guide.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Create internal/modules/auth/ module structure" - }, - "scope": { - "in": ["Add internal/modules/auth package with module definition and provider scaffolding"], - "out": ["Implementing auth behavior"] - }, - "requirements": [ - "MUST create internal/modules/auth/ with module definition and provider placeholders", - "MUST keep module definition deterministic" - ], - "acceptance_criteria": [ - "Given the hello-mysql example, when the auth module is imported, then the project builds without unresolved symbols" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Auth module files exist and tests compile"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/auth/module.go", - "examples/hello-mysql/internal/modules/auth/providers.go" - ], - "depends_on": [], - "risks": ["Module naming conflicts with existing modules"], - "estimate": { "tshirt": "S", "rationale": "New package scaffolding" }, - "owner_type": "agent" - }, - { - "id": "T-002", - "story_id": "ST-001", - "title": "Implement JWT middleware", - "motivation": "Demonstrate JWT auth by validating tokens in middleware.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Implement JWT middleware with token validation" - }, - "scope": { - "in": ["JWT validation middleware for hello-mysql"], - "out": ["OAuth or other auth flows"] - }, - "requirements": [ - "MUST validate JWT signature and expiry", - "MUST reject requests with missing or invalid tokens", - "SHOULD make validation configuration explicit in example config" - ], - "acceptance_criteria": [ - "Given a request without a token, when it hits a protected route, then it returns an auth error", - "Given a request with a valid token, when it hits a protected route, then it proceeds" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Auth middleware tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/auth/middleware.go", - "examples/hello-mysql/internal/modules/auth/config.go" - ], - "depends_on": ["T-001"], - "risks": ["JWT library choice may differ from docs"], - "estimate": { "tshirt": "M", "rationale": "Middleware + config" }, - "owner_type": "agent" - }, - { - "id": "T-003", - "story_id": "ST-001", - "title": "Add typed user context helpers", - "motivation": "Expose authenticated user info via request context per guide.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Add typed context helpers for user extraction" - }, - "scope": { - "in": ["Typed context keys and helper accessors"], - "out": ["User persistence or profile logic"] - }, - "requirements": [ - "MUST provide typed context accessors for user info", - "MUST document usage in code comments or README" - ], - "acceptance_criteria": [ - "Given a request with a valid token, when a handler reads the context helper, then it receives user info" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Handlers compile with context helper usage"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/auth/context.go" - ], - "depends_on": ["T-002"], - "risks": ["Context key collisions if not namespaced"], - "estimate": { "tshirt": "S", "rationale": "Small helper API" }, - "owner_type": "agent" - }, - { - "id": "T-004", - "story_id": "ST-001", - "title": "Add /auth/login token endpoint", - "motivation": "Provide a runnable token generation endpoint for the example.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Create /auth/login endpoint for token generation" - }, - "scope": { - "in": ["Login handler that issues JWT for a sample user"], - "out": ["Real password storage or hashing"] - }, - "requirements": [ - "MUST expose /auth/login endpoint", - "MUST return a signed JWT on success", - "SHOULD keep sample credentials explicit in docs" - ], - "acceptance_criteria": [ - "Given valid sample credentials, when POST /auth/login is called, then it returns a JWT" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Login endpoint test returns JWT"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/auth/handler.go", - "examples/hello-mysql/internal/modules/auth/routes.go" - ], - "depends_on": ["T-001", "T-002"], - "risks": ["Endpoint behavior may diverge from docs"], - "estimate": { "tshirt": "M", "rationale": "Handler + wiring" }, - "owner_type": "agent" - }, - { - "id": "T-005", - "story_id": "ST-001", - "title": "Protect /users routes with auth", - "motivation": "Show mixed public and authenticated endpoints in example.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Protect existing /users CRUD routes (except GET list)" - }, - "scope": { - "in": ["Apply auth middleware to /users routes except list"], - "out": ["Changing user business logic"] - }, - "requirements": [ - "MUST require auth on create/update/delete user endpoints", - "MUST leave GET list publicly accessible" - ], - "acceptance_criteria": [ - "Given no token, when POST /users is called, then it returns an auth error", - "Given a valid token, when POST /users is called, then it proceeds" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Protected route tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/users/routes.go" - ], - "depends_on": ["T-002", "T-003"], - "risks": ["Route refactor might affect tests"], - "estimate": { "tshirt": "S", "rationale": "Middleware wiring" }, - "owner_type": "agent" - }, - { - "id": "T-006", - "story_id": "ST-001", - "title": "Add auth module tests", - "motivation": "Ensure auth flows are validated in unit and integration tests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Add auth module tests (unit + integration)" - }, - "scope": { - "in": ["Unit tests for middleware and integration tests for routes"], - "out": ["Load testing"] - }, - "requirements": [ - "MUST include tests for auth success and failure cases", - "SHOULD cover context extraction in handlers" - ], - "acceptance_criteria": [ - "Given invalid tokens, when tests run, then auth failure cases are asserted", - "Given valid tokens, when tests run, then protected routes succeed" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Auth unit and integration tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/auth/auth_test.go", - "examples/hello-mysql/internal/modules/auth/integration_test.go" - ], - "depends_on": ["T-001", "T-002", "T-003", "T-004", "T-005"], - "risks": ["Integration tests may require database fixtures"], - "estimate": { "tshirt": "M", "rationale": "Multiple test types" }, - "owner_type": "agent" - }, - { - "id": "T-007", - "story_id": "ST-001", - "title": "Update README with auth examples", - "motivation": "Ensure example README documents auth usage.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 1: Authentication Module", - "quote": "Update README with auth usage examples" - }, - "scope": { - "in": ["Document auth routes and sample usage in example README"], - "out": ["Broader doc changes outside README"] - }, - "requirements": [ - "MUST include example request for /auth/login", - "MUST describe which /users routes require auth" - ], - "acceptance_criteria": [ - "Given the README, when a user follows the auth example, then the endpoints are correct" - ], - "verification": { - "commands": ["rg -n 'auth/login' examples/hello-mysql/README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes auth endpoint usage"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/README.md" - ], - "depends_on": ["T-006"], - "risks": ["README drift if routes change"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only change" }, - "owner_type": "agent" - }, - { - "id": "T-008", - "story_id": "ST-002", - "title": "Add validation helper package", - "motivation": "Provide shared validation utilities for example requests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Add validation helper package in internal/validation/" - }, - "scope": { - "in": ["internal/validation helpers and error types"], - "out": ["Cross-repo validation framework"] - }, - "requirements": [ - "MUST add internal/validation package with helper functions", - "MUST keep API minimal and example-focused" - ], - "acceptance_criteria": [ - "Given a request struct, when validation helpers are called, then they return structured errors" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Validation helpers compile and tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/validation/validation.go" - ], - "depends_on": [], - "risks": ["Helper API could diverge from guide wording"], - "estimate": { "tshirt": "S", "rationale": "Small helper package" }, - "owner_type": "agent" - }, - { - "id": "T-009", - "story_id": "ST-002", - "title": "Validate CreateUserRequest fields", - "motivation": "Show field-level validation on create requests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Implement field-level validation for CreateUserRequest" - }, - "scope": { - "in": ["Validation for CreateUserRequest in handlers"], - "out": ["Changing persistence logic"] - }, - "requirements": [ - "MUST validate required fields on CreateUserRequest", - "MUST return structured validation errors" - ], - "acceptance_criteria": [ - "Given missing fields, when POST /users is called, then it returns field-level validation errors" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["CreateUserRequest validation tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/users/requests.go", - "examples/hello-mysql/internal/modules/users/handlers.go" - ], - "depends_on": ["T-008"], - "risks": ["Validation rules may need alignment with docs"], - "estimate": { "tshirt": "S", "rationale": "Handler changes" }, - "owner_type": "agent" - }, - { - "id": "T-010", - "story_id": "ST-002", - "title": "Validate UpdateUserRequest fields", - "motivation": "Show field-level validation on update requests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Implement field-level validation for UpdateUserRequest" - }, - "scope": { - "in": ["Validation for UpdateUserRequest in handlers"], - "out": ["Changing update semantics"] - }, - "requirements": [ - "MUST validate required fields on UpdateUserRequest", - "MUST return structured validation errors" - ], - "acceptance_criteria": [ - "Given invalid fields, when PUT /users/{id} is called, then it returns field-level errors" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["UpdateUserRequest validation tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/users/requests.go", - "examples/hello-mysql/internal/modules/users/handlers.go" - ], - "depends_on": ["T-008"], - "risks": ["Validation rules may need alignment with docs"], - "estimate": { "tshirt": "S", "rationale": "Handler changes" }, - "owner_type": "agent" - }, - { - "id": "T-011", - "story_id": "ST-002", - "title": "Add RFC 7807 validation error response", - "motivation": "Return Problem Details responses for validation errors.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Add validation error response type (RFC 7807 extension)" - }, - "scope": { - "in": ["Define RFC 7807 response and wire into validation handlers"], - "out": ["Global error handling refactor"] - }, - "requirements": [ - "MUST define a Problem Details response type with field errors", - "MUST use the response for validation failures" - ], - "acceptance_criteria": [ - "Given a validation failure, when a request is processed, then it returns RFC 7807 with field errors" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Validation error responses match RFC 7807 structure"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/validation/problem_details.go" - ], - "depends_on": ["T-008"], - "risks": ["Existing error responses may conflict"], - "estimate": { "tshirt": "S", "rationale": "New type + wiring" }, - "owner_type": "agent" - }, - { - "id": "T-012", - "story_id": "ST-002", - "title": "Add query parameter validation example", - "motivation": "Demonstrate validation for list pagination query parameters.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Add query parameter validation example (list pagination)" - }, - "scope": { - "in": ["Validate pagination query parameters in list handler"], - "out": ["New pagination features"] - }, - "requirements": [ - "MUST validate pagination query parameters", - "MUST return RFC 7807 responses for invalid params" - ], - "acceptance_criteria": [ - "Given invalid pagination values, when GET /users is called, then it returns field-level errors" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Pagination validation tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/users/handlers.go" - ], - "depends_on": ["T-008", "T-011"], - "risks": ["Changing list handler behavior impacts examples"], - "estimate": { "tshirt": "S", "rationale": "Small handler update" }, - "owner_type": "agent" - }, - { - "id": "T-013", - "story_id": "ST-002", - "title": "Add validation tests", - "motivation": "Ensure validation helpers and handlers are covered by tests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Add validation tests" - }, - "scope": { - "in": ["Unit tests for validation helpers and handler validation flows"], - "out": ["End-to-end load tests"] - }, - "requirements": [ - "MUST cover create, update, and pagination validation cases", - "SHOULD assert RFC 7807 response shape" - ], - "acceptance_criteria": [ - "Given validation scenarios, when tests run, then all validation cases pass" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Validation test suite passes"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/validation/validation_test.go", - "examples/hello-mysql/internal/modules/users/validation_test.go" - ], - "depends_on": ["T-008", "T-009", "T-010", "T-011", "T-012"], - "risks": ["Test data may overlap with auth changes"], - "estimate": { "tshirt": "M", "rationale": "Multiple test cases" }, - "owner_type": "agent" - }, - { - "id": "T-014", - "story_id": "ST-002", - "title": "Document validation patterns in README", - "motivation": "Expose validation usage in the example README.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 2: Request Validation", - "quote": "Document validation patterns in example README" - }, - "scope": { - "in": ["Add validation usage examples to README"], - "out": ["Changes to guides"] - }, - "requirements": [ - "MUST include examples for request body and query validation", - "MUST reference RFC 7807 error format" - ], - "acceptance_criteria": [ - "Given the README, when a user reads validation section, then examples match routes" - ], - "verification": { - "commands": ["rg -n 'validation' examples/hello-mysql/README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes validation section"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/README.md" - ], - "depends_on": ["T-013"], - "risks": ["README may need consistent formatting"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-015", - "story_id": "ST-003", - "title": "Add CORS middleware configuration", - "motivation": "Demonstrate CORS middleware configuration in example.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Add CORS middleware configuration" - }, - "scope": { - "in": ["CORS middleware configuration in hello-mysql"], - "out": ["Full CORS policy management"] - }, - "requirements": [ - "MUST configure CORS middleware with explicit allowed origins and methods", - "SHOULD expose configuration via example config" - ], - "acceptance_criteria": [ - "Given a cross-origin request, when it hits the server, then CORS headers are present" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["CORS middleware tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/middleware/cors.go", - "examples/hello-mysql/internal/config/config.go" - ], - "depends_on": [], - "risks": ["CORS headers may vary across environments"], - "estimate": { "tshirt": "S", "rationale": "Small middleware" }, - "owner_type": "agent" - }, - { - "id": "T-016", - "story_id": "ST-003", - "title": "Implement rate limiting middleware", - "motivation": "Show rate limiting middleware using golang.org/x/time/rate.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Implement rate limiting middleware using golang.org/x/time/rate" - }, - "scope": { - "in": ["Rate limiting middleware with configurable limits"], - "out": ["Distributed rate limiting"] - }, - "requirements": [ - "MUST use golang.org/x/time/rate for rate limiting", - "MUST allow configuration of rate and burst" - ], - "acceptance_criteria": [ - "Given requests above the limit, when they are sent, then the handler returns a rate limit error" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Rate limiting tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/middleware/rate_limit.go" - ], - "depends_on": [], - "risks": ["Tests may depend on timing"], - "estimate": { "tshirt": "M", "rationale": "Middleware + tests" }, - "owner_type": "agent" - }, - { - "id": "T-017", - "story_id": "ST-003", - "title": "Create timing/metrics middleware example", - "motivation": "Demonstrate custom middleware as a provider.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Create timing/metrics middleware example" - }, - "scope": { - "in": ["Timing/metrics middleware with logging output"], - "out": ["Metrics backend integration"] - }, - "requirements": [ - "MUST record request duration and log it", - "SHOULD be registered as a provider to demonstrate DI" - ], - "acceptance_criteria": [ - "Given a request, when the middleware runs, then it logs duration" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Timing middleware tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/middleware/timing.go" - ], - "depends_on": [], - "risks": ["Logging output may be noisy in tests"], - "estimate": { "tshirt": "S", "rationale": "Simple middleware" }, - "owner_type": "agent" - }, - { - "id": "T-018", - "story_id": "ST-003", - "title": "Add route group example for middleware", - "motivation": "Show scoped middleware using route groups.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Add route group example (/api/v1/ prefix)" - }, - "scope": { - "in": ["Route group example with /api/v1 prefix and scoped middleware"], - "out": ["Full API versioning refactor"] - }, - "requirements": [ - "MUST demonstrate route group with scoped middleware", - "SHOULD use /api/v1 prefix for the group" - ], - "acceptance_criteria": [ - "Given grouped routes, when middleware is applied to the group, then it affects only those routes" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Grouped middleware tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/http/router.go" - ], - "depends_on": [], - "risks": ["Overlap with Story 5 refactor"], - "estimate": { "tshirt": "M", "rationale": "Routing changes" }, - "owner_type": "agent" - }, - { - "id": "T-019", - "story_id": "ST-003", - "title": "Register middleware as providers", - "motivation": "Show middleware registration through DI providers.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Register middleware as providers for dependency injection" - }, - "scope": { - "in": ["Provider registration for middleware"], - "out": ["Framework-level DI changes"] - }, - "requirements": [ - "MUST register CORS, rate limiting, and timing middleware as providers", - "MUST demonstrate ordering in registration" - ], - "acceptance_criteria": [ - "Given middleware providers, when the app boots, then middleware is resolved via DI" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Middleware provider wiring compiles and tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/app/module.go" - ], - "depends_on": ["T-015", "T-016", "T-017"], - "risks": ["Provider order may affect behavior"], - "estimate": { "tshirt": "S", "rationale": "Wiring changes" }, - "owner_type": "agent" - }, - { - "id": "T-020", - "story_id": "ST-003", - "title": "Add middleware tests", - "motivation": "Validate middleware behavior and ordering.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Add middleware tests" - }, - "scope": { - "in": ["Tests for CORS, rate limiting, timing, and group scoping"], - "out": ["Performance benchmarks"] - }, - "requirements": [ - "MUST cover CORS, rate limiting, and timing middleware", - "MUST verify middleware ordering and group scoping" - ], - "acceptance_criteria": [ - "Given middleware tests, when executed, then all middleware behaviors are asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Middleware test suite passes"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/middleware/middleware_test.go" - ], - "depends_on": ["T-015", "T-016", "T-017", "T-018", "T-019"], - "risks": ["Timing-based tests may be flaky"], - "estimate": { "tshirt": "M", "rationale": "Multiple middleware tests" }, - "owner_type": "agent" - }, - { - "id": "T-021", - "story_id": "ST-003", - "title": "Document middleware patterns in README", - "motivation": "Expose middleware patterns and ordering in README.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 3: Advanced Middleware Patterns", - "quote": "Document middleware patterns in example README" - }, - "scope": { - "in": ["README updates for middleware examples"], - "out": ["Guide changes"] - }, - "requirements": [ - "MUST include examples for CORS and rate limiting", - "MUST describe middleware ordering" - ], - "acceptance_criteria": [ - "Given the README, when users read middleware section, then examples match code" - ], - "verification": { - "commands": ["rg -n 'middleware' examples/hello-mysql/README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes middleware section"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/README.md" - ], - "depends_on": ["T-020"], - "risks": ["README may need formatting updates"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-022", - "story_id": "ST-004", - "title": "Add database cleanup interface", - "motivation": "Demonstrate resource cleanup responsibilities for the DB module.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns", - "quote": "Add cleanup interface and implementation to database module" - }, - "scope": { - "in": ["Cleanup interface and implementation in database module"], - "out": ["New database abstractions"] - }, - "requirements": [ - "MUST provide a cleanup method for database module", - "MUST document cleanup order expectations" - ], - "acceptance_criteria": [ - "Given the database module, when shutdown occurs, then cleanup is invoked" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Cleanup implementation compiles and tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/database/module.go", - "examples/hello-mysql/internal/modules/database/cleanup.go" - ], - "depends_on": [], - "risks": ["Cleanup ordering may be unclear"], - "estimate": { "tshirt": "S", "rationale": "Small interface" }, - "owner_type": "agent" - }, - { - "id": "T-023", - "story_id": "ST-004", - "title": "Implement graceful shutdown hook", - "motivation": "Demonstrate graceful shutdown with in-flight request handling.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns", - "quote": "Implement graceful shutdown hook in main" - }, - "scope": { - "in": ["Shutdown hook wiring in hello-mysql main"], - "out": ["Deployment scripts"] - }, - "requirements": [ - "MUST add graceful shutdown handling for HTTP server", - "MUST call cleanup interfaces on shutdown" - ], - "acceptance_criteria": [ - "Given a shutdown signal, when the app exits, then cleanup is called in order" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Lifecycle tests validate shutdown behavior"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/cmd/hello-mysql/main.go" - ], - "depends_on": ["T-022"], - "risks": ["Graceful shutdown may need timeouts"], - "estimate": { "tshirt": "M", "rationale": "Main wiring changes" }, - "owner_type": "agent" - }, - { - "id": "T-024", - "story_id": "ST-004", - "title": "Add context cancellation example", - "motivation": "Demonstrate cancellation patterns in long-running operations.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns", - "quote": "Add context cancellation example for long-running operations" - }, - "scope": { - "in": ["Example handler or service showing context cancellation"], - "out": ["Production job orchestration"] - }, - "requirements": [ - "MUST demonstrate context cancellation in a long-running operation", - "SHOULD show error handling for canceled context" - ], - "acceptance_criteria": [ - "Given a request that is canceled, when the operation runs, then it stops early and returns a canceled error" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Context cancellation tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/users/service.go" - ], - "depends_on": ["T-023"], - "risks": ["Cancellation timing in tests may be sensitive"], - "estimate": { "tshirt": "S", "rationale": "Example change" }, - "owner_type": "agent" - }, - { - "id": "T-025", - "story_id": "ST-004", - "title": "Document cleanup order (LIFO)", - "motivation": "Make cleanup ordering explicit for example users.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns", - "quote": "Document cleanup order (LIFO)" - }, - "scope": { - "in": ["Add cleanup order documentation to README"], - "out": ["Guide changes"] - }, - "requirements": [ - "MUST document LIFO cleanup ordering", - "MUST indicate where cleanup hooks are registered" - ], - "acceptance_criteria": [ - "Given the README, when users read lifecycle section, then cleanup order is described" - ], - "verification": { - "commands": ["rg -n 'cleanup' examples/hello-mysql/README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes cleanup order"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/README.md" - ], - "depends_on": ["T-022", "T-023"], - "risks": ["Docs may need updates if hooks change"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-026", - "story_id": "ST-004", - "title": "Add lifecycle tests", - "motivation": "Validate cleanup and shutdown behavior with tests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns", - "quote": "Add lifecycle tests" - }, - "scope": { - "in": ["Tests for cleanup order and graceful shutdown"], - "out": ["Load testing"] - }, - "requirements": [ - "MUST cover cleanup invocation order", - "MUST cover graceful shutdown behavior" - ], - "acceptance_criteria": [ - "Given shutdown tests, when executed, then cleanup order is asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Lifecycle test suite passes"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/lifecycle/lifecycle_test.go" - ], - "depends_on": ["T-022", "T-023", "T-024"], - "risks": ["Tests may be timing sensitive"], - "estimate": { "tshirt": "M", "rationale": "Integration-style tests" }, - "owner_type": "agent" - }, - { - "id": "T-027", - "story_id": "ST-004", - "title": "Update README with lifecycle patterns", - "motivation": "Document lifecycle patterns for example users.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 4: Lifecycle & Cleanup Patterns", - "quote": "Update README with lifecycle patterns" - }, - "scope": { - "in": ["README updates for lifecycle and shutdown patterns"], - "out": ["Guide changes"] - }, - "requirements": [ - "MUST describe graceful shutdown", - "MUST reference cleanup hooks" - ], - "acceptance_criteria": [ - "Given the README, when users follow lifecycle section, then steps match code" - ], - "verification": { - "commands": ["rg -n 'shutdown' examples/hello-mysql/README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes lifecycle section"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/README.md" - ], - "depends_on": ["T-026"], - "risks": ["README drift if shutdown behavior changes"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-028", - "story_id": "ST-005", - "title": "Refactor routes to /api/v1 prefix", - "motivation": "Demonstrate API versioning via route prefixing.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning", - "quote": "Refactor routes to use /api/v1/ prefix" - }, - "scope": { - "in": ["Move example routes under /api/v1"], - "out": ["Adding new API versions"] - }, - "requirements": [ - "MUST refactor routes to use /api/v1 prefix", - "MUST update route tests accordingly" - ], - "acceptance_criteria": [ - "Given the server, when routes are listed, then endpoints are under /api/v1" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Route tests pass with /api/v1 prefix"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/http/router.go" - ], - "depends_on": ["T-018"], - "risks": ["Refactor could break doc references"], - "estimate": { "tshirt": "M", "rationale": "Routing changes" }, - "owner_type": "agent" - }, - { - "id": "T-029", - "story_id": "ST-005", - "title": "Add route group with auth middleware", - "motivation": "Demonstrate scoped middleware for authenticated routes.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning", - "quote": "Add route group with auth middleware" - }, - "scope": { - "in": ["Route group using auth middleware"], - "out": ["Changing auth behavior"] - }, - "requirements": [ - "MUST apply auth middleware to a specific route group", - "MUST keep public routes outside the group" - ], - "acceptance_criteria": [ - "Given grouped routes, when auth middleware is applied, then only grouped routes require auth" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Auth group routing tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/http/router.go" - ], - "depends_on": ["T-028", "T-002"], - "risks": ["Auth middleware order may be incorrect"], - "estimate": { "tshirt": "S", "rationale": "Group wiring" }, - "owner_type": "agent" - }, - { - "id": "T-030", - "story_id": "ST-005", - "title": "Add nested route group example", - "motivation": "Demonstrate nested groups such as /api/v1/admin.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning", - "quote": "Add nested group example (e.g., /api/v1/admin/)" - }, - "scope": { - "in": ["Nested route group example"], - "out": ["Admin authorization logic"] - }, - "requirements": [ - "MUST demonstrate nested route groups", - "SHOULD add a sample admin handler" - ], - "acceptance_criteria": [ - "Given nested groups, when routes are registered, then /api/v1/admin is scoped correctly" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Nested group tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/http/router.go", - "examples/hello-mysql/internal/modules/admin/handlers.go" - ], - "depends_on": ["T-028"], - "risks": ["New admin module may need scaffolding"], - "estimate": { "tshirt": "M", "rationale": "New routes + handler" }, - "owner_type": "agent" - }, - { - "id": "T-031", - "story_id": "ST-005", - "title": "Update controller grouping usage", - "motivation": "Ensure controllers demonstrate grouping patterns.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning", - "quote": "Update controller to demonstrate grouping" - }, - "scope": { - "in": ["Controller updates to use route groups"], - "out": ["Controller API refactor"] - }, - "requirements": [ - "MUST register routes via groups where appropriate", - "MUST keep public and protected endpoints separated" - ], - "acceptance_criteria": [ - "Given the controller, when routes are registered, then group structure matches routing plan" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Controllers compile and routing tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/users/controller.go" - ], - "depends_on": ["T-028"], - "risks": ["Controller refactor may affect auth routing"], - "estimate": { "tshirt": "S", "rationale": "Refactor routing registration" }, - "owner_type": "agent" - }, - { - "id": "T-032", - "story_id": "ST-005", - "title": "Add routing tests for groups", - "motivation": "Verify grouped route behavior and path prefixing.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning", - "quote": "Add routing tests for groups" - }, - "scope": { - "in": ["Routing tests for /api/v1 and nested groups"], - "out": ["Load tests"] - }, - "requirements": [ - "MUST cover /api/v1 prefix and nested group routes", - "MUST verify middleware scoping for grouped routes" - ], - "acceptance_criteria": [ - "Given routing tests, when executed, then grouped routes resolve correctly" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Routing group tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/http/router_test.go" - ], - "depends_on": ["T-028", "T-029", "T-030", "T-031"], - "risks": ["Tests may overlap with middleware tests"], - "estimate": { "tshirt": "M", "rationale": "Multiple routing cases" }, - "owner_type": "agent" - }, - { - "id": "T-033", - "story_id": "ST-005", - "title": "Document routing patterns", - "motivation": "Expose route grouping and versioning in README.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 5: Route Groups & API Versioning", - "quote": "Document routing patterns" - }, - "scope": { - "in": ["README updates for route grouping"], - "out": ["Guide changes"] - }, - "requirements": [ - "MUST describe /api/v1 prefix and nested groups", - "MUST include example route group code snippet" - ], - "acceptance_criteria": [ - "Given the README, when users read routing section, then groups match code" - ], - "verification": { - "commands": ["rg -n '/api/v1' examples/hello-mysql/README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes /api/v1 routing section"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/README.md" - ], - "depends_on": ["T-032"], - "risks": ["README may need updates if paths change"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-034", - "story_id": "ST-006", - "title": "Add buildVisibility unit tests", - "motivation": "Ensure buildVisibility has direct unit coverage.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Add unit tests for buildVisibility() in kernel" - }, - "scope": { - "in": ["Unit tests in modkit/kernel"], - "out": ["Refactoring buildVisibility implementation"] - }, - "requirements": [ - "MUST add direct unit tests for buildVisibility", - "SHOULD cover module visibility edge cases" - ], - "acceptance_criteria": [ - "Given buildVisibility inputs, when tests run, then expected visibility rules are asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Kernel unit tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "modkit/kernel/visibility_test.go" - ], - "depends_on": ["T-007", "T-014", "T-021", "T-027", "T-033"], - "risks": ["Existing tests may require updates"], - "estimate": { "tshirt": "S", "rationale": "Unit tests only" }, - "owner_type": "agent" - }, - { - "id": "T-035", - "story_id": "ST-006", - "title": "Add ProviderBuildError tests", - "motivation": "Cover provider build error scenarios in kernel tests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Add tests for ProviderBuildError scenarios" - }, - "scope": { - "in": ["Provider build error tests"], - "out": ["Provider behavior changes"] - }, - "requirements": [ - "MUST add tests for ProviderBuildError cases", - "SHOULD cover missing provider dependencies" - ], - "acceptance_criteria": [ - "Given invalid providers, when kernel builds, then ProviderBuildError is asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Provider build error tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "modkit/kernel/provider_errors_test.go" - ], - "depends_on": ["T-007", "T-014", "T-021", "T-027", "T-033"], - "risks": ["May require new fixtures"], - "estimate": { "tshirt": "S", "rationale": "Unit tests only" }, - "owner_type": "agent" - }, - { - "id": "T-036", - "story_id": "ST-006", - "title": "Add ControllerBuildError tests", - "motivation": "Cover controller build errors with explicit tests.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Add tests for ControllerBuildError scenarios" - }, - "scope": { - "in": ["Controller build error tests"], - "out": ["Controller behavior changes"] - }, - "requirements": [ - "MUST add tests for ControllerBuildError cases", - "SHOULD cover missing dependencies" - ], - "acceptance_criteria": [ - "Given invalid controllers, when kernel builds, then ControllerBuildError is asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Controller build error tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "modkit/kernel/controller_errors_test.go" - ], - "depends_on": ["T-007", "T-014", "T-021", "T-027", "T-033"], - "risks": ["May require new fixtures"], - "estimate": { "tshirt": "S", "rationale": "Unit tests only" }, - "owner_type": "agent" - }, - { - "id": "T-037", - "story_id": "ST-006", - "title": "Add HTTP middleware error recovery tests", - "motivation": "Cover middleware edge cases in HTTP adapter.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Add HTTP middleware error recovery tests" - }, - "scope": { - "in": ["HTTP middleware error recovery tests"], - "out": ["HTTP adapter refactor"] - }, - "requirements": [ - "MUST add tests for middleware error recovery", - "SHOULD cover panic recovery or error propagation" - ], - "acceptance_criteria": [ - "Given middleware errors, when tests run, then recovery behavior is asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["HTTP middleware tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "modkit/http/middleware_test.go" - ], - "depends_on": ["T-007", "T-014", "T-021", "T-027", "T-033"], - "risks": ["Test may need new fixtures"], - "estimate": { "tshirt": "S", "rationale": "Unit tests" }, - "owner_type": "agent" - }, - { - "id": "T-038", - "story_id": "ST-006", - "title": "Add router edge case tests", - "motivation": "Cover router conflicts and invalid method cases.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Add router edge case tests (conflicts, invalid methods)" - }, - "scope": { - "in": ["Router edge case tests"], - "out": ["Router implementation changes"] - }, - "requirements": [ - "MUST add tests for route conflicts", - "MUST add tests for invalid methods" - ], - "acceptance_criteria": [ - "Given invalid routes, when router builds, then errors are asserted" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Router edge case tests pass"], - "manual_steps": [] - }, - "artifacts": [ - "modkit/http/router_test.go" - ], - "depends_on": ["T-007", "T-014", "T-021", "T-027", "T-033"], - "risks": ["Existing router tests may need updates"], - "estimate": { "tshirt": "S", "rationale": "Unit tests" }, - "owner_type": "agent" - }, - { - "id": "T-039", - "story_id": "ST-006", - "title": "Ensure new example features have tests", - "motivation": "Maintain coverage for new example features.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Ensure all new example features have tests" - }, - "scope": { - "in": ["Add or extend example tests for auth, validation, middleware, lifecycle, routing"], - "out": ["Performance testing"] - }, - "requirements": [ - "MUST add tests for newly added example features", - "SHOULD cover auth, validation, middleware, lifecycle, routing" - ], - "acceptance_criteria": [ - "Given example features, when tests run, then each feature has coverage" - ], - "verification": { - "commands": ["make test"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Example tests cover all new features"], - "manual_steps": [] - }, - "artifacts": [ - "examples/hello-mysql/internal/modules/auth/auth_test.go", - "examples/hello-mysql/internal/validation/validation_test.go", - "examples/hello-mysql/internal/middleware/middleware_test.go", - "examples/hello-mysql/internal/http/router_test.go" - ], - "depends_on": ["T-007", "T-014", "T-021", "T-027", "T-033"], - "risks": ["Test additions may be redundant with earlier tasks"], - "estimate": { "tshirt": "M", "rationale": "Cross-feature tests" }, - "owner_type": "agent" - }, - { - "id": "T-040", - "story_id": "ST-006", - "title": "Update testing guide with new patterns", - "motivation": "Align docs testing guide with new example patterns.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 6: Test Coverage Improvements", - "quote": "Update testing guide with new patterns" - }, - "scope": { - "in": ["docs/guides/testing.md updates"], - "out": ["Other guides"] - }, - "requirements": [ - "MUST add references to new example tests", - "MUST keep guide aligned with example code" - ], - "acceptance_criteria": [ - "Given the testing guide, when reviewed, then it references new example tests" - ], - "verification": { - "commands": ["rg -n 'testing' docs/guides/testing.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Testing guide references updated tests"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/testing.md" - ], - "depends_on": ["T-039"], - "risks": ["Guide may need more detailed examples"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-041", - "story_id": "ST-007", - "title": "Audit authentication guide vs example", - "motivation": "Ensure authentication guide references working example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Audit docs/guides/authentication.md vs example code" - }, - "scope": { - "in": ["Review auth guide against hello-mysql auth example"], - "out": ["Content rewrite beyond references"] - }, - "requirements": [ - "MUST identify mismatches between guide and example code", - "SHOULD note required updates for references" - ], - "acceptance_criteria": [ - "Given the auth guide, when reviewed, then all example references are accurate" - ], - "verification": { - "commands": ["rg -n 'auth' docs/guides/authentication.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Auth guide references updated example paths"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/authentication.md" - ], - "depends_on": ["T-040"], - "risks": ["Guide may require broader edits"], - "estimate": { "tshirt": "XS", "rationale": "Doc audit" }, - "owner_type": "agent" - }, - { - "id": "T-042", - "story_id": "ST-007", - "title": "Audit validation guide vs example", - "motivation": "Ensure validation guide references working example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Audit docs/guides/validation.md vs example code" - }, - "scope": { - "in": ["Review validation guide against example code"], - "out": ["Content rewrite beyond references"] - }, - "requirements": [ - "MUST identify mismatches between guide and example", - "SHOULD prepare reference updates" - ], - "acceptance_criteria": [ - "Given the validation guide, when reviewed, then example references are accurate" - ], - "verification": { - "commands": ["rg -n 'validation' docs/guides/validation.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Validation guide references updated example paths"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/validation.md" - ], - "depends_on": ["T-040"], - "risks": ["Guide may need code snippet updates"], - "estimate": { "tshirt": "XS", "rationale": "Doc audit" }, - "owner_type": "agent" - }, - { - "id": "T-043", - "story_id": "ST-007", - "title": "Audit middleware guide vs example", - "motivation": "Ensure middleware guide references working example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Audit docs/guides/middleware.md vs example code" - }, - "scope": { - "in": ["Review middleware guide against example code"], - "out": ["Content rewrite beyond references"] - }, - "requirements": [ - "MUST identify mismatches between guide and example", - "SHOULD prepare reference updates" - ], - "acceptance_criteria": [ - "Given the middleware guide, when reviewed, then example references are accurate" - ], - "verification": { - "commands": ["rg -n 'middleware' docs/guides/middleware.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Middleware guide references updated example paths"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/middleware.md" - ], - "depends_on": ["T-040"], - "risks": ["Guide may require snippet updates"], - "estimate": { "tshirt": "XS", "rationale": "Doc audit" }, - "owner_type": "agent" - }, - { - "id": "T-044", - "story_id": "ST-007", - "title": "Audit lifecycle guide vs example", - "motivation": "Ensure lifecycle guide references working example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Audit docs/guides/lifecycle.md vs example code" - }, - "scope": { - "in": ["Review lifecycle guide against example code"], - "out": ["Content rewrite beyond references"] - }, - "requirements": [ - "MUST identify mismatches between guide and example", - "SHOULD prepare reference updates" - ], - "acceptance_criteria": [ - "Given the lifecycle guide, when reviewed, then example references are accurate" - ], - "verification": { - "commands": ["rg -n 'lifecycle' docs/guides/lifecycle.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Lifecycle guide references updated example paths"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/lifecycle.md" - ], - "depends_on": ["T-040"], - "risks": ["Guide may require snippet updates"], - "estimate": { "tshirt": "XS", "rationale": "Doc audit" }, - "owner_type": "agent" - }, - { - "id": "T-045", - "story_id": "ST-007", - "title": "Update guides with correct code references", - "motivation": "Align guide references with actual example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Update guides with correct code references" - }, - "scope": { - "in": ["Update guide references and snippets"], - "out": ["New documentation topics"] - }, - "requirements": [ - "MUST update auth, validation, middleware, and lifecycle guides with correct references", - "MUST ensure snippets reflect actual example code" - ], - "acceptance_criteria": [ - "Given updated guides, when a reader follows the references, then they point to existing files" - ], - "verification": { - "commands": ["rg -n 'examples/hello-mysql' docs/guides"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Guides include correct example references"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/authentication.md", - "docs/guides/validation.md", - "docs/guides/middleware.md", - "docs/guides/lifecycle.md" - ], - "depends_on": ["T-041", "T-042", "T-043", "T-044"], - "risks": ["References may change during implementation"], - "estimate": { "tshirt": "S", "rationale": "Docs update" }, - "owner_type": "agent" - }, - { - "id": "T-046", - "story_id": "ST-007", - "title": "Add See example links to guides", - "motivation": "Help users navigate from guides to example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Add \"See example\" links to each guide" - }, - "scope": { - "in": ["Add See example links in each guide"], - "out": ["New guide content"] - }, - "requirements": [ - "MUST add explicit example links to each guide", - "SHOULD keep link format consistent" - ], - "acceptance_criteria": [ - "Given the guides, when viewed, then each guide includes a See example link" - ], - "verification": { - "commands": ["rg -n 'See example' docs/guides"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["Each guide includes a See example link"], - "manual_steps": [] - }, - "artifacts": [ - "docs/guides/authentication.md", - "docs/guides/validation.md", - "docs/guides/middleware.md", - "docs/guides/lifecycle.md" - ], - "depends_on": ["T-045"], - "risks": ["Links may need to be updated if paths change"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - }, - { - "id": "T-047", - "story_id": "ST-007", - "title": "Update main README with feature matrix", - "motivation": "Provide a feature matrix linking docs to example code.", - "spec_ref": { - "path": ".cursor/specs/epic-01-examples-enhancement.md", - "section": "Story 7: Documentation Synchronization", - "quote": "Update main README with feature matrix" - }, - "scope": { - "in": ["Add feature matrix in README"], - "out": ["New feature implementation"] - }, - "requirements": [ - "MUST add a feature matrix mapping patterns to example code", - "MUST include links to relevant guides" - ], - "acceptance_criteria": [ - "Given the main README, when a user reads the matrix, then each pattern links to examples and guides" - ], - "verification": { - "commands": ["rg -n 'feature matrix' README.md"], - "ci_checks": ["CI - Pull Request"], - "evidence": ["README includes feature matrix section"], - "manual_steps": [] - }, - "artifacts": [ - "README.md" - ], - "depends_on": ["T-046"], - "risks": ["README structure may need reformatting"], - "estimate": { "tshirt": "XS", "rationale": "Doc-only" }, - "owner_type": "agent" - } -] diff --git a/docs/specs/epic-02-core-nest-compatibility.md b/docs/specs/epic-02-core-nest-compatibility.md new file mode 100644 index 0000000..ee6d8cb --- /dev/null +++ b/docs/specs/epic-02-core-nest-compatibility.md @@ -0,0 +1,375 @@ +# Epic 02: Core NestJS Compatibility + +## Overview + +This epic brings modkit to feature parity with NestJS's core module system, implementing the features that make sense in Go's idiomatic context while documenting why certain NestJS features are intentionally skipped or implemented differently. + +**Goals:** +1. Implement graceful shutdown with `io.Closer` support +2. Implement module re-exporting +3. Create comprehensive NestJS compatibility documentation + +## Deliverables + +### 1. Graceful Shutdown + +**Problem:** Applications need to cleanly shut down database connections, flush buffers, and release resources when receiving termination signals. + +**NestJS approach:** 5 lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, `onModuleDestroy`, `beforeApplicationShutdown`, `onApplicationShutdown`) + +**Go-idiomatic approach:** Leverage the standard `io.Closer` interface and Go's signal handling. + +#### API Design + +```go +// App gains a Close method +type App struct { + Controllers map[string]any + // internal: ordered list of closers +} + +// Close shuts down the application gracefully. +// Calls Close() on all providers implementing io.Closer +// in reverse initialization order. +func (a *App) Close() error + +// CloseContext is like Close but respects context cancellation. +func (a *App) CloseContext(ctx context.Context) error +``` + +#### Provider Cleanup + +Providers that need cleanup implement `io.Closer`: + +```go +type DatabaseConnection struct { + db *sql.DB +} + +func (d *DatabaseConnection) Close() error { + return d.db.Close() +} +``` + +The kernel tracks which providers implement `io.Closer` and calls them in reverse order during `App.Close()`. + +#### Signal Handling Helper (Optional) + +```go +// Serve starts the HTTP server and handles graceful shutdown on SIGINT/SIGTERM. +// This is a convenience wrapper - users can also handle signals themselves. +func ServeWithShutdown(ctx context.Context, addr string, handler http.Handler, app *App) error +``` + +Or users can handle signals themselves (standard Go pattern): + +```go +func main() { + app, _ := kernel.Bootstrap(&AppModule{}) + + // Standard Go signal handling + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + + server := &http.Server{Addr: ":8080", Handler: router} + + go func() { + <-ctx.Done() + server.Shutdown(context.Background()) + app.Close() + }() + + server.ListenAndServe() +} +``` + +#### Implementation Details + +1. **Track initialization order:** Container records order providers are built +2. **Detect io.Closer:** When provider is built, check if it implements `io.Closer` +3. **Close in reverse order:** On `App.Close()`, iterate closers in reverse +4. **Error aggregation:** Collect all close errors, return as multi-error +5. **Idempotent:** Multiple calls to `Close()` are safe (no-op after first) + +#### Acceptance Criteria + +- [ ] `App.Close()` method implemented +- [ ] `App.CloseContext(ctx)` method for timeout support +- [ ] Providers implementing `io.Closer` are called in reverse init order +- [ ] Multiple close errors aggregated into single error +- [ ] Close is idempotent (safe to call multiple times) +- [ ] Tests for close ordering +- [ ] Tests for error aggregation +- [ ] Example updated to demonstrate graceful shutdown +- [ ] Documentation in `docs/guides/lifecycle.md` updated + +--- + +### 2. Module Re-exporting + +**Problem:** A module may want to re-export tokens from its imports, creating a facade or aggregating multiple modules. + +**NestJS example:** +```typescript +@Module({ + imports: [CommonModule], + exports: [CommonModule], // Re-export everything from CommonModule +}) +export class CoreModule {} +``` + +**modkit approach:** Allow exporting tokens that come from imported modules. + +#### API Design + +Current behavior: Exports can only contain tokens from the module's own providers. + +New behavior: Exports can also contain: +1. Tokens from own providers (current) +2. Tokens exported by imported modules (new) + +```go +func (m *CoreModule) Definition() module.ModuleDef { + return module.ModuleDef{ + Name: "core", + Imports: []module.Module{m.common, m.config}, + Exports: []module.Token{ + "common.logger", // Re-export from CommonModule + "config.settings", // Re-export from ConfigModule + }, + } +} +``` + +#### Alternative: Export entire module + +Could also support exporting an entire module's exports: + +```go +Exports: []module.Token{ + module.All(m.common), // Re-export all exports from CommonModule +} +``` + +This is more complex and may not be worth it for v1. Start with explicit token re-export. + +#### Implementation Details + +1. **Visibility check update:** When validating exports, check if token is: + - Defined in own providers, OR + - Exported by an imported module +2. **Transitive visibility:** If A imports B, and B re-exports from C, A can access C's re-exported tokens +3. **No re-exporting non-exported tokens:** Can only re-export what the imported module exports + +#### Acceptance Criteria + +- [ ] Modules can export tokens from imported modules +- [ ] Validation: cannot re-export non-exported tokens (clear error) +- [ ] Transitive re-exporting works (A→B→C) +- [ ] Tests for re-export scenarios +- [ ] Tests for invalid re-export attempts +- [ ] Documentation updated + +--- + +### 3. NestJS Compatibility Documentation + +Create `docs/guides/nestjs-compatibility.md` documenting how modkit maps to NestJS concepts. + +#### Document Structure + +```markdown +# NestJS Compatibility Guide + +This guide documents how modkit implements (or intentionally differs from) +NestJS concepts for Go developers coming from the Node.js ecosystem. + +## Feature Matrix + +| NestJS Feature | modkit Status | Notes | +|----------------|---------------|-------| +| ... | ... | ... | + +## Detailed Comparison + +### Modules +... + +### Providers +... + +### Lifecycle +... +``` + +#### Feature Matrix Content + +| Category | NestJS Feature | modkit Status | Notes | +|----------|----------------|---------------|-------| +| **Modules** | +| | Module definition | ✅ Implemented | `ModuleDef` struct vs `@Module()` decorator | +| | Imports | ✅ Implemented | Same concept | +| | Exports | ✅ Implemented | Same concept | +| | Providers | ✅ Implemented | Same concept | +| | Controllers | ✅ Implemented | Same concept | +| | Global modules | ⏭️ Skipped | Anti-pattern in Go; prefer explicit imports | +| | Dynamic modules | ⏭️ Different | Use constructor functions with options | +| | Module re-exporting | 🔄 This Epic | Exporting tokens from imported modules | +| **Providers** | +| | Singleton scope | ✅ Implemented | Default and only scope | +| | Request scope | ⏭️ Skipped | Use context.Context instead | +| | Transient scope | ⏭️ Skipped | Use factory functions if needed | +| | useClass | ✅ Implemented | Via `Build` function | +| | useValue | ✅ Implemented | Via `Build` returning static value | +| | useFactory | ✅ Implemented | `Build` function IS a factory | +| | useExisting | ⏭️ Skipped | Use token aliases in Build function | +| | Async providers | ⏭️ Different | Go is sync; use goroutines if needed | +| **Lifecycle** | +| | onModuleInit | ⏭️ Skipped | Put init logic in `Build()` function | +| | onApplicationBootstrap | ⏭️ Skipped | Controllers built = app bootstrapped | +| | onModuleDestroy | ✅ This Epic | Via `io.Closer` interface | +| | beforeApplicationShutdown | ⏭️ Skipped | Covered by `io.Closer` | +| | onApplicationShutdown | ✅ This Epic | `App.Close()` method | +| | enableShutdownHooks | ⏭️ Different | Use `signal.NotifyContext` (Go stdlib) | +| **HTTP** | +| | Controllers | ✅ Implemented | `RouteRegistrar` interface | +| | Route decorators | ⏭️ Different | Explicit `RegisterRoutes()` method | +| | Middleware | ✅ Implemented | Standard `func(http.Handler) http.Handler` | +| | Guards | ⏭️ Different | Implement as middleware | +| | Interceptors | ⏭️ Different | Implement as middleware | +| | Pipes | ⏭️ Different | Validation in handler or middleware | +| | Exception filters | ⏭️ Different | Error handling middleware | +| **Other** | +| | CLI scaffolding | ❌ Not planned | Go boilerplate is minimal | +| | Devtools | ❌ Not planned | Use standard Go tooling | +| | Microservices | ❌ Not planned | Out of scope | +| | WebSockets | ❌ Not planned | Use gorilla/websocket directly | +| | GraphQL | ❌ Not planned | Use gqlgen directly | + +#### Justification Sections + +For each "Skipped" or "Different" feature, document: +1. What NestJS does +2. Why it doesn't fit Go +3. The Go-idiomatic alternative + +Example: + +```markdown +### Global Modules + +**NestJS:** The `@Global()` decorator makes a module's exports available +everywhere without explicit imports. + +**modkit:** Not implemented. + +**Justification:** Global modules contradict Go's explicit dependency philosophy. +In Go, if a package needs something, it imports it explicitly. This makes +dependencies visible in code and easier to trace. modkit's core value +proposition is visibility enforcement - adding global modules would undermine this. + +**Alternative:** If you need a provider available to many modules: +1. Create the module once with a constructor function +2. Import it explicitly where needed +3. The singleton nature means all modules share the same instance + +​```go +// Create once +configModule := NewConfigModule() + +// Import explicitly where needed +usersModule := NewUsersModule(configModule) +ordersModule := NewOrdersModule(configModule) +​``` +``` + +#### Acceptance Criteria + +- [ ] `docs/guides/nestjs-compatibility.md` created +- [ ] Feature matrix with all major NestJS features +- [ ] Justification for each skipped/different feature +- [ ] Go-idiomatic alternatives documented +- [ ] Cross-linked from README and other relevant docs + +--- + +## Stories Breakdown + +### Story 2.1: Graceful Shutdown - Core Implementation +**Points:** 3 + +- Implement `App.Close()` method +- Track provider initialization order in Container +- Detect `io.Closer` implementations +- Close in reverse order +- Unit tests for close ordering + +### Story 2.2: Graceful Shutdown - Error Handling +**Points:** 2 + +- Aggregate multiple close errors +- Make Close idempotent +- Implement `App.CloseContext(ctx)` with timeout +- Tests for error scenarios + +### Story 2.3: Graceful Shutdown - Example & Docs +**Points:** 2 + +- Update hello-mysql example with graceful shutdown +- Update `docs/guides/lifecycle.md` +- Add signal handling example + +### Story 2.4: Module Re-exporting - Implementation +**Points:** 3 + +- Update visibility validation to allow re-exports +- Update graph builder for transitive re-exports +- Validate re-exports are actually exported by import +- Unit tests for re-export scenarios + +### Story 2.5: Module Re-exporting - Docs +**Points:** 1 + +- Update `docs/guides/modules.md` with re-export examples +- Add error message examples for invalid re-exports + +### Story 2.6: NestJS Compatibility Documentation +**Points:** 3 + +- Create `docs/guides/nestjs-compatibility.md` +- Write feature matrix +- Write justifications for skipped features +- Write Go-idiomatic alternatives +- Cross-link from README + +--- + +## Total Estimate + +| Story | Points | +|-------|--------| +| 2.1 Graceful Shutdown - Core | 3 | +| 2.2 Graceful Shutdown - Errors | 2 | +| 2.3 Graceful Shutdown - Docs | 2 | +| 2.4 Module Re-exporting | 3 | +| 2.5 Re-exporting Docs | 1 | +| 2.6 NestJS Compatibility Docs | 3 | +| **Total** | **14** | + +--- + +## Dependencies + +- None (builds on existing kernel/module packages) + +## Risks + +1. **Close ordering complexity:** If providers have circular dependencies (which should be rejected), close ordering is undefined. Mitigation: Circular deps already rejected at build time. + +2. **io.Closer detection:** Interface detection in Go is implicit. Risk: Some types might unexpectedly implement io.Closer. Mitigation: Only check providers, document behavior clearly. + +## Success Metrics + +- hello-mysql example demonstrates clean shutdown +- Users can migrate from NestJS with clear documentation +- No breaking changes to existing API diff --git a/docs/specs/epic-03-performance-benchmarks.md b/docs/specs/epic-03-performance-benchmarks.md new file mode 100644 index 0000000..bd81941 --- /dev/null +++ b/docs/specs/epic-03-performance-benchmarks.md @@ -0,0 +1,527 @@ +# Epic 03: Performance Benchmarks + +## Overview + +Create a comprehensive benchmark suite comparing modkit against NestJS and Go DI alternatives. The benchmarks demonstrate that modkit delivers NestJS-style architecture with Go's performance characteristics. + +**Goals:** +1. Quantify modkit's performance vs NestJS (cross-language) +2. Compare modkit vs Go alternatives (wire, fx, do) +3. Provide reproducible, automated benchmarks +4. Generate clear visualizations for documentation + +**Repository:** `github.com/go-modkit/benchmarks` (new repo) + +--- + +## Benchmark Categories + +### 1. HTTP Throughput + +Measure requests per second under sustained load. + +| Metric | Tool | Command | +|--------|------|---------| +| RPS (requests/sec) | wrk | `wrk -t12 -c400 -d30s` | +| Latency distribution | wrk | p50, p75, p90, p99 | + +### 2. Resource Usage + +Measure memory and CPU consumption. + +| Metric | Tool | Method | +|--------|------|--------| +| Memory (RSS) | docker stats | Peak during load test | +| Memory (idle) | docker stats | After startup, before load | +| CPU % | docker stats | Average during load test | + +### 3. Startup Time + +Measure cold start performance. + +| Metric | Method | +|--------|--------| +| Bootstrap time | Time from process start to first request ready | +| Build time (Go) | `time go build` | +| Compile time (NestJS) | `time npm run build` | + +### 4. Scalability + +Measure performance across different app sizes. + +| Scenario | Providers | Modules | Purpose | +|----------|-----------|---------|---------| +| Small | 5 | 2 | Minimal overhead | +| Medium | 25 | 5 | Typical app | +| Large | 100 | 20 | Stress test | + +--- + +## Frameworks Under Test + +### Primary Comparison + +| Framework | Language | Type | Why Include | +|-----------|----------|------|-------------| +| **modkit** | Go | Module system | Subject | +| **NestJS** | Node.js | Module system | Inspiration, cross-language | + +### Go Alternatives + +| Framework | Type | Why Include | +|-----------|------|-------------| +| **No framework** | Manual wiring | Baseline | +| **google/wire** | Compile-time codegen | Industry standard | +| **uber-go/fx** | Reflection-based | Similar to NestJS | +| **samber/do** | Generics-based | Modern alternative | + +--- + +## Test Application + +All frameworks implement the same application with identical behavior. + +### Architecture + +``` +AppModule +├── ConfigModule +│ └── ConfigProvider (reads env vars) +├── DatabaseModule +│ └── ConnectionProvider (mock or real DB) +└── UsersModule + ├── UsersController + ├── UsersService + └── UsersRepository +``` + +### Endpoints + +| Method | Path | Description | DB? | +|--------|------|-------------|-----| +| GET | `/health` | Health check | No | +| GET | `/users` | List users (paginated) | Yes | +| GET | `/users/:id` | Get user by ID | Yes | +| POST | `/users` | Create user | Yes | +| PUT | `/users/:id` | Update user | Yes | +| DELETE | `/users/:id` | Delete user | Yes | + +### Response Format + +```json +{ + "id": 1, + "name": "John Doe", + "email": "john@example.com", + "createdAt": "2024-01-15T10:30:00Z" +} +``` + +### Database + +Use SQLite in-memory for consistency: +- No network latency variance +- Same SQL across all implementations +- Fast reset between runs + +--- + +## Repository Structure + +``` +github.com/go-modkit/benchmarks/ +├── README.md # Results and methodology +├── METHODOLOGY.md # Detailed benchmark methodology +├── docker-compose.yml # Run all benchmarks +├── Makefile # Convenience commands +│ +├── apps/ +│ ├── modkit/ +│ │ ├── main.go +│ │ ├── go.mod +│ │ ├── modules/ +│ │ │ ├── config/ +│ │ │ ├── database/ +│ │ │ └── users/ +│ │ └── Dockerfile +│ │ +│ ├── nestjs/ +│ │ ├── src/ +│ │ │ ├── app.module.ts +│ │ │ ├── config/ +│ │ │ ├── database/ +│ │ │ └── users/ +│ │ ├── package.json +│ │ ├── tsconfig.json +│ │ └── Dockerfile +│ │ +│ ├── wire/ +│ │ ├── main.go +│ │ ├── wire.go +│ │ ├── wire_gen.go +│ │ └── Dockerfile +│ │ +│ ├── fx/ +│ │ ├── main.go +│ │ └── Dockerfile +│ │ +│ ├── do/ +│ │ ├── main.go +│ │ └── Dockerfile +│ │ +│ └── baseline/ # No framework, manual wiring +│ ├── main.go +│ └── Dockerfile +│ +├── scripts/ +│ ├── run-all.sh # Run complete benchmark suite +│ ├── run-single.sh # Run single framework +│ ├── warmup.sh # Warmup requests before benchmark +│ ├── collect-metrics.sh # Collect docker stats +│ └── generate-report.py # Generate charts and tables +│ +├── results/ +│ ├── latest/ # Symlink to most recent +│ │ ├── raw/ # Raw benchmark output +│ │ ├── summary.json # Parsed results +│ │ ├── charts/ # Generated charts +│ │ └── report.md # Generated report +│ └── archive/ +│ └── 2024-01-15/ +│ +└── .github/ + └── workflows/ + ├── benchmark.yml # Manual trigger + └── scheduled.yml # Weekly run +``` + +--- + +## Benchmark Execution + +### Prerequisites + +- Docker and Docker Compose +- wrk (HTTP benchmarking tool) +- Python 3 (for chart generation) + +### Running Benchmarks + +```bash +# Clone the repo +git clone https://github.com/go-modkit/benchmarks +cd benchmarks + +# Run all benchmarks +make benchmark + +# Run specific framework +make benchmark-modkit +make benchmark-nestjs + +# Generate report +make report +``` + +### Benchmark Script Flow + +``` +1. Build all Docker images +2. For each framework: + a. Start container + b. Wait for health check + c. Record startup time + d. Warmup (1000 requests) + e. Run benchmark (30s sustained load) + f. Collect memory/CPU stats + g. Stop container +3. Parse results +4. Generate charts +5. Generate report +``` + +### Benchmark Parameters + +```bash +# wrk configuration +THREADS=12 +CONNECTIONS=400 +DURATION=30s + +# Runs per framework (for statistical significance) +RUNS=3 +``` + +--- + +## Results Presentation + +### README.md Summary + +```markdown +# modkit Benchmarks + +Comparing modkit against NestJS and Go DI frameworks. + +## Latest Results (2024-01-15) + +### HTTP Throughput (GET /users/:id) + +| Framework | RPS | Latency p50 | Latency p99 | Memory | +|-----------|-----|-------------|-------------|--------| +| baseline | 52,000 | 1.8ms | 6.2ms | 8MB | +| modkit | 48,000 | 2.0ms | 7.1ms | 12MB | +| wire | 51,000 | 1.9ms | 6.5ms | 9MB | +| fx | 45,000 | 2.2ms | 8.0ms | 18MB | +| do | 47,000 | 2.1ms | 7.5ms | 14MB | +| NestJS | 9,500 | 11ms | 42ms | 95MB | + +### Requests per Second (Higher is Better) + +[Chart: Bar chart showing RPS for each framework] + +### Latency Distribution (Lower is Better) + +[Chart: Box plot showing latency distribution] + +### Memory Usage (Lower is Better) + +[Chart: Bar chart showing memory consumption] + +## Important Notes + +This benchmark compares Go frameworks to a Node.js framework (NestJS). +The performance difference primarily reflects Go vs Node.js runtime +characteristics, not just framework design. + +### Why Compare to NestJS? + +modkit is inspired by NestJS's module architecture. This benchmark +demonstrates that you can have the same architectural benefits with +Go's performance profile. + +### When to Choose NestJS + +- Team expertise in TypeScript/Node.js +- Need for NestJS's rich decorator ecosystem +- Rapid prototyping where raw performance isn't critical + +### When to Choose modkit + +- Performance-critical services +- Resource-constrained environments +- Preference for explicit over implicit behavior +- Existing Go expertise +``` + +### Chart Types + +1. **Bar Chart: Requests per Second** + - All frameworks side by side + - Color-coded: Go (blue), Node.js (orange) + +2. **Box Plot: Latency Distribution** + - Shows p50, p75, p90, p99 for each framework + - Highlights tail latency differences + +3. **Bar Chart: Memory Usage** + - Idle memory vs peak memory + - Stacked or grouped bars + +4. **Line Chart: Scalability** + - X-axis: Number of providers + - Y-axis: RPS or startup time + - Shows how each framework scales + +--- + +## Stories Breakdown + +### Story 3.1: Repository Setup +**Points:** 2 + +- Create `go-modkit/benchmarks` repo +- Set up directory structure +- Create Makefile with common commands +- Write initial README with methodology + +### Story 3.2: modkit Test App +**Points:** 2 + +- Implement modkit app with all endpoints +- SQLite in-memory database +- Dockerfile with optimized build +- Verify all endpoints work + +### Story 3.3: NestJS Test App +**Points:** 3 + +- Implement NestJS app with identical endpoints +- Match response formats exactly +- SQLite with TypeORM or Prisma +- Dockerfile with production build +- Verify behavior matches modkit app + +### Story 3.4: Go Alternatives (wire, fx, do, baseline) +**Points:** 4 + +- Implement same app in each framework +- Ensure identical behavior +- Dockerfiles for each +- Verify all endpoints + +### Story 3.5: Benchmark Scripts +**Points:** 3 + +- Write `run-all.sh` orchestration script +- Implement warmup routine +- Collect docker stats (memory, CPU) +- Record startup times +- Output raw results to JSON + +### Story 3.6: Report Generation +**Points:** 3 + +- Python script to parse results +- Generate charts (matplotlib or plotly) +- Generate markdown tables +- Create summary.json + +### Story 3.7: CI/CD Integration +**Points:** 2 + +- GitHub Actions workflow for manual trigger +- Optional: scheduled weekly runs +- Upload results as artifacts +- Auto-commit to results/ directory + +### Story 3.8: Documentation +**Points:** 2 + +- Write METHODOLOGY.md +- Document how to run locally +- Document how to interpret results +- Link from main modkit README + +--- + +## Total Estimate + +| Story | Points | +|-------|--------| +| 3.1 Repository Setup | 2 | +| 3.2 modkit Test App | 2 | +| 3.3 NestJS Test App | 3 | +| 3.4 Go Alternatives | 4 | +| 3.5 Benchmark Scripts | 3 | +| 3.6 Report Generation | 3 | +| 3.7 CI/CD Integration | 2 | +| 3.8 Documentation | 2 | +| **Total** | **21** | + +--- + +## Technical Decisions + +### 1. SQLite for Database + +**Decision:** Use SQLite in-memory for all tests. + +**Rationale:** +- Eliminates network latency variance +- Same SQL dialect works for Go and Node.js +- Fast reset between benchmark runs +- No external database container needed + +### 2. Docker for Isolation + +**Decision:** Run each framework in its own Docker container. + +**Rationale:** +- Consistent environment +- Easy memory/CPU measurement via docker stats +- Reproducible across machines +- Clear resource boundaries + +### 3. wrk for Load Testing + +**Decision:** Use wrk (not ab, siege, or k6). + +**Rationale:** +- High performance, low overhead +- Lua scripting for complex scenarios +- Widely used and understood +- Available on all platforms + +### 4. Multiple Runs + +**Decision:** Run each benchmark 3 times, report median. + +**Rationale:** +- Reduces variance from system noise +- More statistically meaningful +- Catches outliers + +### 5. Warmup Period + +**Decision:** Send 1000 requests before measuring. + +**Rationale:** +- JIT compilation for Node.js +- Connection pool warming +- CPU frequency scaling +- Consistent starting state + +--- + +## Fair Comparison Guidelines + +### What We Control + +1. **Identical endpoints** - Same routes, same response format +2. **Same database** - SQLite in-memory for all +3. **Same hardware** - Run on identical Docker resource limits +4. **Same load** - Same wrk parameters for all +5. **Warmup** - Same warmup for all frameworks + +### What We Acknowledge + +1. **Language difference** - Go is compiled, Node.js is interpreted +2. **Runtime difference** - Go has different GC than V8 +3. **Framework philosophy** - Some prioritize DX over performance + +### Transparency Requirements + +- Publish all source code +- Document exact versions (Go, Node, framework versions) +- Document hardware/VM specs +- Provide instructions to reproduce + +--- + +## Success Metrics + +1. **Reproducibility** - Anyone can clone and run benchmarks +2. **Fairness** - No artificial handicaps on any framework +3. **Clarity** - Results are easy to understand +4. **Usefulness** - Helps users make informed decisions + +--- + +## Risks + +| Risk | Mitigation | +|------|------------| +| Unfair comparison claims | Document methodology transparently | +| Results vary by machine | Use Docker with resource limits | +| Framework updates invalidate results | Include version numbers, re-run periodically | +| NestJS community backlash | Frame as "different tools for different needs" | + +--- + +## Future Enhancements + +1. **More frameworks** - Gin, Echo, Fiber (HTTP only, no DI) +2. **More scenarios** - WebSocket, file upload, streaming +3. **Cloud benchmarks** - AWS Lambda cold starts +4. **Interactive dashboard** - Web UI for exploring results