THOUGHT: [What I need to find/understand and why]
ACTION: [The specific tool and parameters I will use]
OBSERVATION: [What I learned from the result]
THOUGHT: [How this informs my next step]

# Code Exploration Scratchpad: [Task Title]

Task: [task file path]
Created: [date]

---

## Problem Definition

[Stage 2 content...]

## Exploration Log

[Stage 3 findings with THOUGHT/ACTION/OBSERVATION entries...]

## Architecture Analysis

[Stage 4 analysis...]

## Implementation Details

[Stage 5 synthesis...]


## Self-Critique

[Stage 7 verification...]

## Problem Definition

### Analysis Questions
- Primary: [What is the main question to answer?]
- Secondary: [What supporting questions exist?]

### Search Keywords
- Core domain terms: [list]
- Related feature names: [list]
- Likely file/folder patterns: [list]

### Success Criteria
- [ ] All affected files identified with specific paths
- [ ] Key interfaces and functions documented
- [ ] Integration points mapped
- [ ] Similar implementations found

THOUGHT: User wants to understand the "authentication" feature. Let me think step by step:
1. Authentication features typically have entry points in: API routes, middleware, UI components
2. I should first understand the project structure to know where to look
3. Then search for auth-related keywords in likely locations

ACTION: Glob pattern="**/auth*" to find auth-related files
OBSERVATION: Found files in /src/api/auth.ts, /src/middleware/auth.ts, /src/components/LoginForm.tsx

THOUGHT: Now I have candidate files. The API file is likely the main entry point.
Let me read it to understand the authentication flow.

ACTION: Read file=/src/api/auth.ts
OBSERVATION: Found login(), logout(), refreshToken() functions. Login calls authService.authenticate()

THOUGHT: The entry point delegates to authService. I need to trace this service to understand the full flow.

THOUGHT: I found the entry point at src/api/users.ts:42. Let me trace what happens when createUser() is called.
Let me think about the data flow:
- Input: UserCreateDTO
- Output: UserResponse
- What transformations happen between input and output?

ACTION: Read file=/src/api/users.ts lines=42-80
OBSERVATION: createUser() validates input, calls userService.create(), transforms result

THOUGHT: Three steps identified. Let me trace each:
1. Validation - where is the validation logic? (check for validateUserInput call)
2. Service call - need to read userService.create()
3. Transformation - how is the result mapped to UserResponse?

ACTION: Grep pattern="userService" path=/src/api/users.ts
OBSERVATION: Import from '../services/userService', called at line 55

THOUGHT: Now I need to follow the service layer. This follows Repository pattern - service likely calls a repository for data access.

ACTION: Read file=/src/services/userService.ts
OBSERVATION: create() validates business rules, calls userRepository.save(), emits UserCreated event

THOUGHT: Multiple concerns in service layer:
1. Business validation (different from API validation)
2. Repository interaction (data persistence)
3. Event emission (side effect)
I need to trace all three paths to fully understand the feature.

## Exploration Log

### Entry 1: [Component/Feature Name]
THOUGHT: I need to understand [specific aspect]...
ACTION: [Tool used with parameters]
OBSERVATION:
- File: [path:line]
- Key Facts: [What was found]
- Confidence: [High/Medium/Low]
- New Questions: [If any]

### Entry 2: [Next Component]
...

THOUGHT: Let me identify the architecture pattern. I'll look for evidence:
- Controllers/handlers in /api or /routes = MVC or layered architecture
- Repository files = Repository pattern
- Service files = Service Layer pattern
- Separate read/write models = CQRS

ACTION: Glob pattern="**/*Repository*"
OBSERVATION: Found userRepository.ts, orderRepository.ts in /src/repositories/

ACTION: Glob pattern="**/*Service*"
OBSERVATION: Found userService.ts, orderService.ts in /src/services/

THOUGHT: Evidence suggests a Layered Architecture with:
- API Layer (routes/controllers) - handles HTTP concerns
- Service Layer - business logic orchestration
- Repository Layer - data access abstraction

Let me verify by checking if services depend only on repositories (not on other infrastructure):

ACTION: Grep pattern="import.*from.*repositories" path=/src/services/
OBSERVATION: All services import from repositories, confirming layer boundaries

THOUGHT: Pattern confirmed: Clean layered architecture. Now let me check for cross-cutting concerns...

THOUGHT: The user search function needs analysis. Let me think step by step about performance:
- What data structure is used for search?
- Is there indexing involved?
- Are results paginated or limited?

ACTION: Read file=/src/services/userService.ts lines=120-150 (search function)
OBSERVATION: Uses database query with LIKE operator, has limit parameter

THOUGHT: LIKE queries can be O(n) on table size. Let me check:
1. Is there an index on the searched column?
2. Is the limit enforced at database level?
3. Are results cached?

ACTION: Grep pattern="CREATE INDEX" path=/migrations/
OBSERVATION: Found index on user.email and user.name columns

THOUGHT: Good - indexed columns. But LIKE with leading wildcard ('%term%') won't use index.
Let me verify the query pattern:

ACTION: Read file=/src/repositories/userRepository.ts
OBSERVATION: Query uses 'name LIKE %?%' - this bypasses the index!

THOUGHT: Performance issue identified:
- Index exists but query pattern prevents its use
- This will cause full table scans on large datasets
- Recommendation: implement full-text search or change to prefix matching

---
title: Codebase Impact Analysis - [Task Title]
task_file: [path to task file]
scratchpad: [path to scratchpad file]
created: [date]
status: complete
---

# Codebase Impact Analysis: [Task Title]

## Summary

- **Files to Modify**: X files
- **Files to Create**: Y files
- **Files to Delete**: Z files
- **Test Files Affected**: N files
- **Risk Level**: [Low/Medium/High]

---

## Files to be Modified/Created

Use tree-like file structure format for better readability:

### Primary Changes

### Documentation Updates

---

## Useful Resources for Implementation

### Pattern References

---

## Key Interfaces & Contracts

### Functions/Methods to Modify

| Location | Name | Current Signature | Change Required |
|----------|------|-------------------|-----------------|
| `path/file.ext:L123` | `functionName` | `fn(a: A): B` | [What changes] |

### Classes/Components Affected

| Location | Name | Description | Change Required |
|----------|------|-------------|-----------------|
| `path/file.ext` | `ClassName` | [What it does] | [What changes] |

### Types/Interfaces to Update

| Location | Name | Fields Affected | Change Required |
|----------|------|-----------------|-----------------|
| `path/types.ext` | `TypeName` | [Which fields] | [What changes] |

---

## Integration Points

Files that interact with affected code and may need updates:

| File | Relationship | Impact | Action Needed |
|------|--------------|--------|---------------|
| `path/to/file.ext` | [Imports/Uses/Extends] | [High/Medium/Low] | [What to check] |

---

## Similar Implementations

Reference implementations in the codebase to follow as patterns:

### [Pattern 1]: [Feature Name]

- **Location**: `path/to/similar/`
- **Why relevant**: [How it's similar]
- **Key files**:
  - `file1.ext` - [What to learn from it]
  - `file2.ext` - [What to learn from it]

---

## Test Coverage

### Existing Tests to Update

| Test File | Tests Affected | Update Required |
|-----------|----------------|-----------------|
| `path/test.ext` | [Test names] | [What changes] |

### New Tests Needed

| Test Type | Location | Coverage Target |
|-----------|----------|-----------------|
| [Unit/Integration/E2E] | `path/new-test.ext` | [What to test] |

---

## Risk Assessment

### High Risk Areas

| Area | Risk | Mitigation |
|------|------|------------|
| [Area] | [What could go wrong] | [How to reduce risk] |

---

## Recommended Exploration

Before implementation, developer should read:

1. `path/to/key/file1.ext` - [Why important]
2. `path/to/key/file2.ext` - [Why important]
3. `path/to/key/file3.ext` - [Why important]

---

## Verification Summary

| Check | Status | Notes |
|-------|--------|-------|
| All affected files identified | ✅/⚠️ | [Brief note] |
| Integration points mapped | ✅/⚠️ | [Brief note] |
| Similar patterns found | ✅/⚠️ | [Count] patterns |
| Test coverage analyzed | ✅/⚠️ | [Brief note] |
| Risks assessed | ✅/⚠️ | [Brief note] |

Limitations/Caveats: [Any acknowledged gaps]

### Gaps Found

| Gap | Additional Analysis Needed | Priority |
|-----|---------------------------|----------|
| [Weakness] | [Action to fix] | [Critical/High/Med/Low] |

### Revisions Made
- Gap: [X] → Action: [What I did] → Result: [Evidence of resolution]

Analysis Complete: .specs/analysis/analysis-<name>.md
Scratchpad: .specs/scratchpad/<hex-id>.md
Files Affected: X to modify, Y to create, Z to delete
Risk Level: [Low/Medium/High]
Key Integration Points: [Count]
Similar Patterns Found: [Yes/No - brief description]
Self-Critique: 5 verification questions checked
Gaps Addressed: [Count]

THOUGHT: Let me think step by step about what I need to find:
1. Route definition - where is /users/:id mapped to a handler?
2. Handler logic - what does the handler do?
3. Data retrieval - how is user data fetched?
4. Response formatting - how is the response structured?

ACTION: Grep pattern="users/:id|users/\{id\}" path=/src
OBSERVATION: Match in /src/routes/users.ts:15: router.get('/users/:id', userController.getById)

THOUGHT: Route maps to userController.getById. Let me trace this controller method.

ACTION: Read file=/src/controllers/userController.ts
OBSERVATION:
Line 23-35: getById method
- Extracts id from params
- Calls userService.findById(id)
- Returns 404 if not found
- Returns user with status 200

THOUGHT: Controller handles HTTP concerns, delegates to service. Need to trace service.

ACTION: Read file=/src/services/userService.ts
OBSERVATION:
Line 45-58: findById method
- Validates id format
- Calls userRepository.findById(id)
- Enriches with user preferences
- Returns UserDTO

THOUGHT: Service adds business logic (validation, enrichment). Need to trace repository.

ACTION: Read file=/src/repositories/userRepository.ts
OBSERVATION:
Line 30-42: findById method
- Uses Prisma client
- Includes related entities (profile, settings)
- Returns raw User entity or null

THOUGHT: Complete chain traced. Let me summarize the data flow:
HTTP Request -> Controller (params extraction) -> Service (validation, enrichment) -> Repository (DB query) -> Service (DTO mapping) -> Controller (HTTP response)

Key files:
- Entry: /src/routes/users.ts:15
- Controller: /src/controllers/userController.ts:23-35
- Service: /src/services/userService.ts:45-58
- Repository: /src/repositories/userRepository.ts:30-42

THOUGHT: Authentication is a cross-cutting concern. Let me think step by step:
1. Where is auth enforced? (middleware, guards, decorators?)
2. How is auth state stored? (JWT, session, tokens?)
3. How do protected routes access user info?
4. What happens on auth failure?

ACTION: Glob pattern="**/*auth*"
OBSERVATION:
- /src/middleware/authMiddleware.ts
- /src/services/authService.ts
- /src/utils/jwt.ts

THOUGHT: Three auth-related files. Middleware is likely the enforcement point. Let me trace.

ACTION: Read file=/src/middleware/authMiddleware.ts
OBSERVATION:
- Extracts Bearer token from header
- Calls jwt.verify() to validate
- Attaches decoded user to request.user
- Calls next() on success, returns 401 on failure

THOUGHT: JWT-based auth with middleware pattern. Now I need to understand:
1. How is the middleware applied to routes?
2. What's in the JWT payload?
3. How do downstream handlers use request.user?

ACTION: Grep pattern="authMiddleware" path=/src/routes
OBSERVATION: Applied to: /users (except /users/register), /orders, /admin/*

THOUGHT: Not globally applied - specific routes protected. Let me verify JWT structure:

ACTION: Read file=/src/utils/jwt.ts
OBSERVATION:
- sign() creates token with: userId, email, roles
- verify() returns decoded payload
- Token expires in 24 hours

THOUGHT: JWT contains user identity (userId, email) and authorization (roles).
This means:
1. Authentication: JWT validity = user authenticated
2. Authorization: roles in JWT used for access control
3. User context: handlers access user via request.user.userId

Let me verify role-based access is enforced somewhere:

ACTION: Grep pattern="request.user.roles|req.user.roles" path=/src
OBSERVATION: Found in /src/middleware/roleGuard.ts - checks if user has required role

THOUGHT: Complete picture:
- authMiddleware: validates JWT, extracts user identity
- roleGuard: enforces role-based access control
- Downstream handlers: access user via request.user

Architecture pattern: Middleware chain for auth (authentication) + authorization (roles)