The Socratic Method With Claude Code

flowchart TD
    A["Endpoint is slow (800ms)"] --> B{Where is the time spent?}
    B -->|Query| C{How often does data change?}
    B -->|Mapping| M["Optimize mapper, not cache"]
    B -->|Network| N["Check connection pooling"]
    C -->|Frequently| D{Consistency requirements?}
    C -->|Rarely| E{Multiple instances?}
    D -->|Strict| F["Redis with invalidation"]
    D -->|Eventual OK| G{Infrastructure budget?}
    E -->|Single| H["In-memory cache + TTL"]
    E -->|Multiple| I{Can instances diverge briefly?}
    I -->|Yes| H
    I -->|No| F
    G -->|Have Redis| F
    G -->|Keep it simple| H
    style A fill:#1a1a2e,stroke:#e94560,color:#eee
    style H fill:#0d7377,stroke:#14ffec,color:#eee
    style F fill:#16213e,stroke:#0f3460,color:#eee
    style M fill:#2d132c,stroke:#ee4540,color:#eee
    style N fill:#2d132c,stroke:#ee4540,color:#eee

mindmap
  root((Caching Decision))
    Profile before caching
      Know where the time goes
      Cache the right layer
    Match tool to problem
      Monthly changes != Redis
      In-memory is infrastructure-free
    Multi-instance awareness
      Staleness tolerance drives the choice
      5-min TTL acceptable for pricing
    Avoided
      Unnecessary Redis dependency
      Over-engineering for the problem size

flowchart LR
    subgraph Frontend
        A["PaymentStep.tsx"] --> B["useCompletePayment()"]
    end
    subgraph API
        B -->|"POST /api/payment/complete"| C["PaymentController"]
        C --> D["PaymentService"]
    end
    subgraph Database Operations
        D --> E["1. Insert transaction"]
        E --> F["2. Link services to ad"]
        F --> G["3. Update ad status"]
    end
    E -.->|"No DB transaction wrapping"| H["Risk: partial completion"]
    style H fill:#e94560,stroke:#e94560,color:#fff
    style A fill:#1a1a2e,stroke:#0f3460,color:#eee
    style B fill:#1a1a2e,stroke:#0f3460,color:#eee
    style C fill:#16213e,stroke:#0f3460,color:#eee
    style D fill:#16213e,stroke:#0f3460,color:#eee
    style E fill:#0d7377,stroke:#14ffec,color:#eee
    style F fill:#0d7377,stroke:#14ffec,color:#eee
    style G fill:#0d7377,stroke:#14ffec,color:#eee

mindmap
  root((Payment Flow))
    Entry point
      PaymentStep.tsx button
      useCompletePayment hook
      POST /api/payment/complete
    Backend path
      PaymentController
      PaymentService.completePayment
      ~60 lines of orchestration
    Three critical steps
      Create transaction record
      Link services to job ad
      Update ad status
    Discovery
      No DB transaction wrapper
      Partial failure = user pays but gets nothing
      Need to check production for orphaned transactions

flowchart TB
    subgraph "Your Code"
        EP["POST /api/transactions"]
    end
    subgraph "Issues You Discovered"
        direction TB
        S["Missing org membership check\n(IDOR vulnerability)"]
        V["No min/max on numeric fields\n(negative transactions possible)"]
        E["Raw DB errors exposed to client\n(information leak)"]
        I["No idempotency protection\n(duplicate transactions)"]
    end
    EP --> S
    EP --> V
    EP --> E
    EP --> I
    subgraph "Fixes You Designed"
        S --> S2["Add @OrgMembership() guard"]
        V --> V2["Add @Min(1) @Max(100)"]
        E --> E2["Wrap in try/catch,\nreturn generic 500"]
        I --> I2["Add unique constraint +\nidempotency key header"]
    end
    style S fill:#e94560,stroke:#e94560,color:#fff
    style V fill:#e94560,stroke:#e94560,color:#fff
    style E fill:#e94560,stroke:#e94560,color:#fff
    style I fill:#e94560,stroke:#e94560,color:#fff
    style S2 fill:#0d7377,stroke:#14ffec,color:#eee
    style V2 fill:#0d7377,stroke:#14ffec,color:#eee
    style E2 fill:#0d7377,stroke:#14ffec,color:#eee
    style I2 fill:#0d7377,stroke:#14ffec,color:#eee
    style EP fill:#1a1a2e,stroke:#0f3460,color:#eee

mindmap
  root((Code Review\nQuestions))
    Security
      Who can call this?
      Can they access other users' data?
      What's the authorization model?
    Validation
      What inputs are valid?
      What are the boundary values?
      What does the DTO enforce?
    Error handling
      What if the DB is down?
      What does the user see on failure?
      Do error responses leak internals?
    Consistency
      Is it idempotent?
      What if called twice?
      What if called concurrently?
    Performance
      Will this N+1 query?
      What if there are 10K records?
      Is there an index on the WHERE clause?

graph LR
    subgraph "CRUD Group"
        create --> validate
        create --> uploadFiles
        update --> validate
        update --> uploadFiles
        duplicate --> create
    end
    subgraph "Lifecycle Group"
        publish --> validateStatus["validate (status)"]
        publish --> notifyAdmin
        unpublish --> validateStatus
    end
    subgraph "Query Group"
        findAll
        findById
    end
    style create fill:#0d7377,stroke:#14ffec,color:#eee
    style update fill:#0d7377,stroke:#14ffec,color:#eee
    style duplicate fill:#0d7377,stroke:#14ffec,color:#eee
    style validate fill:#0d7377,stroke:#14ffec,color:#eee
    style uploadFiles fill:#0d7377,stroke:#14ffec,color:#eee
    style publish fill:#e94560,stroke:#e94560,color:#fff
    style unpublish fill:#e94560,stroke:#e94560,color:#fff
    style validateStatus fill:#e94560,stroke:#e94560,color:#fff
    style notifyAdmin fill:#e94560,stroke:#e94560,color:#fff
    style findAll fill:#16213e,stroke:#0f3460,color:#eee
    style findById fill:#16213e,stroke:#0f3460,color:#eee

flowchart TB
    subgraph Before["Before: JobAdService (400 lines)"]
        ALL["Everything in one file"]
    end
    subgraph After["After: 3 focused services"]
        CMD["JobAdCommandService\n~150 lines\ncreate, update, duplicate,\nvalidate, uploadFiles"]
        LCM["JobAdLifecycleService\n~100 lines\npublish, unpublish,\nschedulePublish (new),\nvalidateStatus, notifyAdmin"]
        QRY["JobAdQueryService\n~80 lines\nfindAll, findById,\nfilters, pagination"]
    end
    ALL --> CMD
    ALL --> LCM
    ALL --> QRY
    CMD ---|"shares"| REPO["JobAdRepository"]
    LCM ---|"shares"| REPO
    QRY ---|"shares"| REPO
    style ALL fill:#e94560,stroke:#e94560,color:#fff
    style CMD fill:#0d7377,stroke:#14ffec,color:#eee
    style LCM fill:#0d7377,stroke:#14ffec,color:#eee
    style QRY fill:#0d7377,stroke:#14ffec,color:#eee
    style REPO fill:#16213e,stroke:#0f3460,color:#eee

mindmap
  root((Refactoring\nDecision))
    Why split at all
      400 lines and growing
      6 responsibilities, 3 change-reasons
      Next feature would make it worse
    Why domain split over layer split
      Next feature is scheduled publishing
      Lifecycle service is the natural home
      Layer split would scatter the feature
    Why 3 services not 4
      File uploads only used by CRUD
      Not worth extracting until it grows
      Split the seam that hurts most first
    Shared dependency
      All 3 share JobAdRepository via DI
      No shared mutable state
      Clean, independent modules