@dragonflymcp/plugin 1.0.0

package/templates/examples/architecture/api-design.yaml.template

@@ -0,0 +1,286 @@
+# Zen Architecture Example: RESTful API Design
+#
+# This example demonstrates architecture design for a RESTful API
+# with proper resource modeling, versioning, and error handling.
+
+example_id: "example-arch-api"
+category: "architecture"
+domain: "api-design"
+complexity: "moderate"
+tags: ["api", "rest", "http", "versioning"]
+
+# ============================================================================
+# INPUT
+# ============================================================================
+
+input:
+  story_id: "story-example-002"
+  title: "Create API for task management"
+  description: |
+    Build a RESTful API that allows users to manage their tasks.
+    The API will be consumed by web and mobile clients.
+
+  acceptance_criteria:
+    - criterion: "Given I have a valid auth token, when I POST to /tasks with task data, then a new task is created and returned with 201 status"
+      priority: high
+    - criterion: "Given I own a task, when I GET /tasks/{id}, then I receive the task details"
+      priority: high
+    - criterion: "Given I request a non-existent task, when I GET /tasks/{id}, then I receive 404 with error details"
+      priority: medium
+    - criterion: "Given I send invalid data, when I POST to /tasks, then I receive 400 with validation errors"
+      priority: medium
+
+# ============================================================================
+# OUTPUT
+# ============================================================================
+
+output:
+  arch_id: "arch-example-002"
+  story_id: "story-example-002"
+  status: "completed"
+
+  summary:
+    approach: "RESTful API with JSON:API response format and URL versioning"
+    risk_level: "low"
+    estimated_complexity: "moderate"
+    key_decision: "JSON:API format for consistent, self-documenting responses"
+
+  reasoning:
+    requirements_analysis: |
+      **Functional:**
+      - CRUD operations for tasks
+      - Authentication required
+      - Support multiple clients (web, mobile)
+
+      **Non-Functional:**
+      - Consistent error handling
+      - Discoverable/self-documenting
+      - Versioning for future changes
+      - Pagination for lists
+
+    constraints_identified:
+      - constraint: "Must support web and mobile clients"
+        impact: "Need consistent JSON format, proper CORS"
+      - constraint: "Existing authentication system"
+        impact: "Use JWT tokens from auth system"
+
+  approaches_considered:
+    - name: "Custom JSON format"
+      description: "Define our own response structure"
+      pros:
+        - "Full control over format"
+        - "Can optimize for our use cases"
+      cons:
+        - "Must document everything ourselves"
+        - "Clients need custom parsing"
+        - "Inconsistency risk across endpoints"
+      fit_score: 0.5
+
+    - name: "JSON:API specification"
+      description: "Follow the JSON:API standard (jsonapi.org)"
+      pros:
+        - "Well-documented standard"
+        - "Client libraries available"
+        - "Consistent structure enforced"
+        - "Built-in pagination, filtering, relationships"
+      cons:
+        - "More verbose than minimal JSON"
+        - "Learning curve for standard"
+      fit_score: 0.8
+
+    - name: "GraphQL"
+      description: "Use GraphQL instead of REST"
+      pros:
+        - "Clients request exactly what they need"
+        - "Single endpoint"
+        - "Strong typing"
+      cons:
+        - "Different paradigm - team learning curve"
+        - "Caching more complex"
+        - "Overkill for simple CRUD"
+      fit_score: 0.4
+
+  selected_approach:
+    name: "JSON:API specification"
+    rationale: |
+      JSON:API provides a well-defined structure that:
+      1. Ensures consistency across all endpoints
+      2. Has existing client libraries for web/mobile
+      3. Includes conventions for pagination, errors, relationships
+      4. Is well-documented, reducing our documentation burden
+
+      The verbosity trade-off is acceptable given the benefits of
+      consistency and standardization.
+    confidence: 0.8
+
+  components:
+    - name: "TaskController"
+      responsibility: "Handle HTTP requests for task resources"
+      interface: |
+        GET    /api/v1/tasks          - List tasks (paginated)
+        POST   /api/v1/tasks          - Create task
+        GET    /api/v1/tasks/:id      - Get task
+        PATCH  /api/v1/tasks/:id      - Update task
+        DELETE /api/v1/tasks/:id      - Delete task
+      dependencies: ["TaskService", "ResponseFormatter"]
+
+    - name: "TaskService"
+      responsibility: "Business logic for task operations"
+      interface: |
+        list(userId, filters, pagination) -> { tasks, meta }
+        create(userId, data) -> task
+        get(userId, taskId) -> task
+        update(userId, taskId, data) -> task
+        delete(userId, taskId) -> void
+      dependencies: ["TaskRepository"]
+
+    - name: "ResponseFormatter"
+      responsibility: "Format responses according to JSON:API spec"
+      interface: |
+        success(data, meta?) -> JSON:API response
+        error(errors) -> JSON:API error response
+        paginated(data, pagination) -> JSON:API collection
+      dependencies: []
+
+    - name: "ErrorHandler"
+      responsibility: "Global error handling middleware"
+      interface: |
+        handleError(error, req, res, next)
+      dependencies: ["ResponseFormatter"]
+
+    - name: "ValidationMiddleware"
+      responsibility: "Validate request data against schemas"
+      interface: |
+        validate(schema)(req, res, next)
+      dependencies: []
+
+  technical_decisions:
+    - decision: "URL-based versioning (/api/v1/)"
+      rationale: |
+        URL versioning is explicit, easy to understand, and works with
+        all HTTP clients. Alternative header-based versioning is harder
+        to test and discover.
+      alternatives_rejected:
+        - name: "Header versioning (Accept-Version)"
+          reason: "Harder to test, less discoverable"
+        - name: "No versioning"
+          reason: "Breaking changes would affect all clients"
+
+    - decision: "Use HTTP status codes semantically"
+      rationale: |
+        - 200: Success (GET, PATCH)
+        - 201: Created (POST)
+        - 204: No Content (DELETE)
+        - 400: Validation error
+        - 401: Not authenticated
+        - 403: Not authorized
+        - 404: Not found
+        - 500: Server error
+      alternatives_rejected:
+        - name: "Always return 200 with error in body"
+          reason: "Breaks HTTP semantics, harder for clients"
+
+    - decision: "Pagination with cursor, not offset"
+      rationale: |
+        Cursor-based pagination is stable when data changes (no skipped
+        or duplicate items) and more efficient for large datasets.
+      alternatives_rejected:
+        - name: "Offset/limit pagination"
+          reason: "Unstable with changing data, inefficient at scale"
+
+  risks:
+    - risk: "Breaking changes in future versions"
+      probability: "medium"
+      impact: "medium"
+      mitigation: |
+        1. Version from day one
+        2. Deprecation policy (6 months notice)
+        3. Maintain previous version during transition
+
+    - risk: "Inconsistent error responses"
+      probability: "low"
+      impact: "medium"
+      mitigation: |
+        Global error handler ensures all errors go through
+        ResponseFormatter, maintaining consistency.
+
+  implementation_guidance:
+    - "1. Set up Express router with /api/v1 prefix"
+    - "2. Implement ResponseFormatter for JSON:API format"
+    - "3. Create global ErrorHandler middleware"
+    - "4. Implement ValidationMiddleware with JSON schemas"
+    - "5. Build TaskController with CRUD endpoints"
+    - "6. Add pagination to list endpoint"
+    - "7. Write API tests for each endpoint"
+
+  # Example responses
+  api_examples:
+    success_response: |
+      {
+        "data": {
+          "type": "tasks",
+          "id": "123",
+          "attributes": {
+            "title": "Complete API design",
+            "status": "in_progress",
+            "createdAt": "2025-01-15T10:00:00Z"
+          }
+        }
+      }
+
+    error_response: |
+      {
+        "errors": [
+          {
+            "status": "400",
+            "code": "VALIDATION_ERROR",
+            "title": "Invalid attribute",
+            "detail": "Title must be at least 3 characters",
+            "source": { "pointer": "/data/attributes/title" }
+          }
+        ]
+      }
+
+    collection_response: |
+      {
+        "data": [...],
+        "meta": {
+          "totalCount": 42
+        },
+        "links": {
+          "self": "/api/v1/tasks?page[cursor]=abc",
+          "next": "/api/v1/tasks?page[cursor]=def",
+          "prev": "/api/v1/tasks?page[cursor]=xyz"
+        }
+      }
+
+# ============================================================================
+# TEACHING NOTES
+# ============================================================================
+
+teaching_notes:
+  key_patterns:
+    - pattern: "Standards Adoption"
+      explanation: |
+        Using JSON:API instead of inventing our own format reduces
+        documentation burden and leverages existing ecosystem.
+
+    - pattern: "Semantic HTTP"
+      explanation: |
+        Using HTTP status codes correctly (201 for create, 204 for delete)
+        makes the API predictable and follows industry conventions.
+
+    - pattern: "Cursor Pagination"
+      explanation: |
+        Cursor-based pagination handles real-time data better than
+        offset-based, especially for feeds or frequently-updated lists.
+
+  common_mistakes:
+    - mistake: "Inconsistent error formats across endpoints"
+      better: "Global error handler with standardized format"
+
+    - mistake: "No versioning from the start"
+      better: "Add /v1/ prefix immediately, even if no plans to change"
+
+    - mistake: "Using POST for everything"
+      better: "Use appropriate HTTP methods (GET, POST, PATCH, DELETE)"

package/templates/examples/architecture/oauth-authentication.yaml.template

@@ -0,0 +1,305 @@
+# Zen Architecture Example: OAuth Authentication
+#
+# This example demonstrates a well-structured architecture design
+# for implementing OAuth authentication with multiple providers.
+#
+# Use this as a reference when designing authentication systems.
+
+example_id: "example-arch-oauth"
+category: "architecture"
+domain: "authentication"
+complexity: "moderate"
+tags: ["oauth", "authentication", "security", "jwt"]
+
+# ============================================================================
+# INPUT: The story that triggered this architecture
+# ============================================================================
+
+input:
+  story_id: "story-example-001"
+  title: "Add user authentication with OAuth"
+  description: |
+    Users should be able to log in using their existing Google or GitHub
+    accounts instead of creating new credentials. This improves security
+    (no password storage) and reduces friction for new users.
+
+  acceptance_criteria:
+    - criterion: "Given I am on the login page, when I click 'Sign in with Google', then I am redirected to Google's OAuth consent screen"
+      priority: high
+    - criterion: "Given I complete Google OAuth, when I am redirected back, then I am logged in and see my dashboard"
+      priority: high
+    - criterion: "Given I am logged in, when I close and reopen the browser within 30 days, then I remain logged in"
+      priority: high
+    - criterion: "Given I am logged in, when I click logout, then my session is terminated"
+      priority: medium
+
+# ============================================================================
+# OUTPUT: The architecture design
+# ============================================================================
+
+output:
+  arch_id: "arch-example-001"
+  story_id: "story-example-001"
+  status: "completed"
+
+  summary:
+    approach: "JWT with refresh tokens using passport.js OAuth strategies"
+    risk_level: "medium"
+    estimated_complexity: "moderate"
+    key_decision: "Stateless JWT over server-side sessions for scalability"
+
+  # Explicit reasoning process (Chain-of-Thought)
+  reasoning:
+    requirements_analysis: |
+      **Functional Requirements:**
+      - OAuth with Google and GitHub providers
+      - Persistent login for 30 days
+      - Logout capability
+
+      **Non-Functional Requirements:**
+      - Security: No password storage, secure token handling
+      - Performance: Fast authentication checks
+      - Scalability: Support horizontal scaling
+
+      **Implicit Requirements (inferred):**
+      - Handle OAuth failures gracefully
+      - Support adding new providers in future
+      - Maintain user identity across providers
+
+    constraints_identified:
+      - constraint: "Existing Express.js backend"
+        impact: "Use passport.js ecosystem for consistency"
+      - constraint: "PostgreSQL database"
+        impact: "Store user records and refresh tokens in PostgreSQL"
+      - constraint: "Must support mobile apps in future"
+        impact: "JWT preferred over cookies for mobile compatibility"
+
+  # Always consider multiple approaches
+  approaches_considered:
+    - name: "Server-side sessions with Redis"
+      description: |
+        Traditional session-based auth where session ID is stored in cookie
+        and session data lives in Redis.
+      pros:
+        - "Simple mental model"
+        - "Easy session invalidation (delete from Redis)"
+        - "Server controls all session state"
+      cons:
+        - "Requires Redis infrastructure"
+        - "Sticky sessions or shared session store needed"
+        - "Harder to scale horizontally"
+        - "Not ideal for mobile/API clients"
+      fit_score: 0.6
+
+    - name: "JWT with refresh tokens"
+      description: |
+        Stateless access tokens (short-lived) with rotating refresh tokens
+        (long-lived) stored in database.
+      pros:
+        - "Stateless - easy horizontal scaling"
+        - "No additional infrastructure (Redis)"
+        - "Works well for mobile/API clients"
+        - "Standard approach with good tooling"
+      cons:
+        - "Token revocation requires blocklist or short expiry"
+        - "More complex token rotation logic"
+        - "Larger payload than session ID"
+      fit_score: 0.85
+
+    - name: "OAuth tokens only (no local tokens)"
+      description: |
+        Store and use OAuth provider tokens directly, refreshing
+        through provider when needed.
+      pros:
+        - "Simplest implementation"
+        - "Always fresh user data from provider"
+      cons:
+        - "Dependent on provider availability"
+        - "Can't add local-only features"
+        - "Rate limits from providers"
+        - "Different token formats per provider"
+      fit_score: 0.4
+
+  selected_approach:
+    name: "JWT with refresh tokens"
+    rationale: |
+      This approach best fits our requirements:
+
+      1. **Scalability**: Stateless JWTs allow any server to validate tokens
+         without shared state, critical for horizontal scaling.
+
+      2. **Security**: Short-lived access tokens (15 min) limit exposure window.
+         Refresh token rotation detects token theft.
+
+      3. **Flexibility**: Works for web (cookies) and future mobile (headers).
+
+      4. **Simplicity**: No additional infrastructure beyond our existing
+         PostgreSQL for refresh token storage.
+
+      The main drawback (revocation complexity) is mitigated by short access
+      token expiry - even if compromised, exposure is limited to 15 minutes.
+    confidence: 0.85
+
+  # Component breakdown
+  components:
+    - name: "AuthController"
+      responsibility: "Handle OAuth callbacks and coordinate authentication flow"
+      interface: |
+        GET /auth/google - Initiate Google OAuth
+        GET /auth/google/callback - Handle Google OAuth callback
+        GET /auth/github - Initiate GitHub OAuth
+        GET /auth/github/callback - Handle GitHub OAuth callback
+        POST /auth/refresh - Refresh access token
+        POST /auth/logout - Terminate session
+      dependencies: ["TokenService", "UserService", "passport"]
+
+    - name: "TokenService"
+      responsibility: "JWT creation, validation, and refresh token rotation"
+      interface: |
+        createTokenPair(userId) -> { accessToken, refreshToken }
+        validateAccessToken(token) -> payload | throw
+        refreshTokens(refreshToken) -> { accessToken, refreshToken }
+        revokeRefreshToken(token) -> void
+      dependencies: []
+
+    - name: "UserService"
+      responsibility: "User lookup and creation from OAuth profile"
+      interface: |
+        findOrCreateFromOAuth(provider, profile) -> User
+        findById(userId) -> User
+        linkProvider(userId, provider, providerId) -> void
+      dependencies: ["UserRepository"]
+
+    - name: "AuthMiddleware"
+      responsibility: "Protect routes, extract user from token"
+      interface: |
+        requireAuth(req, res, next) - Block if not authenticated
+        optionalAuth(req, res, next) - Attach user if token present
+      dependencies: ["TokenService"]
+
+    - name: "RefreshTokenRepository"
+      responsibility: "Persist refresh tokens for rotation and revocation"
+      interface: |
+        store(userId, tokenHash, expiresAt) -> void
+        find(tokenHash) -> RefreshToken | null
+        revoke(tokenHash) -> void
+        revokeAllForUser(userId) -> void
+      dependencies: ["Database"]
+
+  # Key technical decisions
+  technical_decisions:
+    - decision: "Use httpOnly cookies for token storage (web)"
+      rationale: |
+        httpOnly cookies prevent JavaScript access, mitigating XSS token theft.
+        Tokens are automatically included in requests, simplifying client code.
+      alternatives_rejected:
+        - name: "localStorage"
+          reason: "Vulnerable to XSS - any script can read tokens"
+        - name: "sessionStorage"
+          reason: "Lost on tab close - poor UX for 30-day persistence"
+
+    - decision: "15-minute access token expiry"
+      rationale: |
+        Short expiry limits damage from token theft. Users won't notice
+        as refresh happens automatically. Balance between security and
+        refresh frequency.
+      alternatives_rejected:
+        - name: "1-hour expiry"
+          reason: "Too long exposure window for sensitive operations"
+        - name: "5-minute expiry"
+          reason: "Too frequent refreshes, unnecessary load"
+
+    - decision: "Rotate refresh tokens on each use"
+      rationale: |
+        If a refresh token is stolen and used, the legitimate user's next
+        refresh will fail (token already rotated), signaling compromise.
+        Attacker can be detected and all tokens revoked.
+      alternatives_rejected:
+        - name: "Static refresh tokens"
+          reason: "Theft goes undetected until expiry"
+
+    - decision: "Hash refresh tokens in database"
+      rationale: |
+        If database is compromised, attacker can't use hashed tokens.
+        Same security principle as password hashing.
+      alternatives_rejected:
+        - name: "Store tokens in plain text"
+          reason: "Database breach = all sessions compromised"
+
+  # Risk assessment
+  risks:
+    - risk: "Refresh token theft enables persistent access"
+      probability: "low"
+      impact: "high"
+      mitigation: |
+        1. Rotate tokens on each use (detect theft)
+        2. Hash tokens in database
+        3. Bind tokens to user agent/IP (optional strictness)
+        4. Provide "logout all devices" feature
+
+    - risk: "OAuth provider outage blocks new logins"
+      probability: "low"
+      impact: "medium"
+      mitigation: |
+        1. Support multiple providers (Google AND GitHub)
+        2. Existing sessions continue to work (JWT validation is local)
+        3. Add email/password as fallback (future enhancement)
+
+    - risk: "JWT secret key compromise"
+      probability: "very low"
+      impact: "critical"
+      mitigation: |
+        1. Store secrets in environment variables, never in code
+        2. Use strong, randomly generated secrets (256+ bits)
+        3. Implement key rotation capability
+        4. Monitor for unusual authentication patterns
+
+  # Implementation guidance
+  implementation_guidance:
+    - "1. Set up passport.js with Google OAuth strategy first (simpler)"
+    - "2. Implement TokenService with JWT signing/verification"
+    - "3. Create RefreshTokenRepository with PostgreSQL"
+    - "4. Add AuthMiddleware and test with Google provider"
+    - "5. Add GitHub strategy (follows same pattern as Google)"
+    - "6. Implement token refresh endpoint"
+    - "7. Add refresh token rotation and reuse detection"
+    - "8. Write integration tests for full OAuth flow"
+
+  open_questions: []
+
+# ============================================================================
+# TEACHING NOTES
+# ============================================================================
+
+teaching_notes:
+  key_patterns:
+    - pattern: "Trade-off Documentation"
+      explanation: |
+        Notice how each approach has explicit pros/cons and a fit_score.
+        This makes the decision-making process transparent and auditable.
+
+    - pattern: "Chain-of-Thought Reasoning"
+      explanation: |
+        The 'reasoning' section shows the thought process explicitly:
+        analyzing requirements, identifying constraints, then evaluating
+        options against those constraints.
+
+    - pattern: "Security by Design"
+      explanation: |
+        Security decisions (httpOnly cookies, token rotation, hashing)
+        are made at architecture time, not retrofitted later.
+
+    - pattern: "Implementation Ordering"
+      explanation: |
+        The guidance section provides a logical order that handles
+        dependencies correctly (TokenService before AuthMiddleware).
+
+  common_mistakes:
+    - mistake: "Jumping to implementation without considering alternatives"
+      better: "Always evaluate 2-3 approaches, even if one seems obvious"
+
+    - mistake: "Storing tokens in localStorage"
+      better: "Use httpOnly cookies for web; secure storage for mobile"
+
+    - mistake: "Long-lived access tokens for 'convenience'"
+      better: "Short access tokens + refresh flow is more secure and just as convenient"