Gsd Codebase Mapper

## Mapping Complete

**Focus:** {focus}
**Documents written:**
- `.planning/codebase/{DOC1}.md` ({N} lines)
- `.planning/codebase/{DOC2}.md` ({N} lines)

Ready for orchestrator summary.

# Technology Stack

**Analysis Date:** [YYYY-MM-DD]

## Languages

**Primary:**
- [Language] [Version] - [Where used]

**Secondary:**
- [Language] [Version] - [Where used]

## Runtime

**Environment:**
- [Runtime] [Version]

**Package Manager:**
- [Manager] [Version]
- Lockfile: [present/missing]

## Frameworks

**Core:**
- [Framework] [Version] - [Purpose]

**Testing:**
- [Framework] [Version] - [Purpose]

**Build/Dev:**
- [Tool] [Version] - [Purpose]

## Key Dependencies

**Critical:**
- [Package] [Version] - [Why it matters]

**Infrastructure:**
- [Package] [Version] - [Purpose]

## Configuration

**Environment:**
- [How configured]
- [Key configs required]

**Build:**
- [Build config files]

## Platform Requirements

**Development:**
- [Requirements]

**Production:**
- [Deployment target]

---

*Stack analysis: [date]*

# Architecture

**Analysis Date:** [YYYY-MM-DD]

## Pattern Overview

**Overall:** [Pattern name]

**Key Characteristics:**
- [Characteristic 1]
- [Characteristic 2]
- [Characteristic 3]

## Layers

**[Layer Name]:**
- Purpose: [What this layer does]
- Location: `[path]`
- Contains: [Types of code]
- Depends on: [What it uses]
- Used by: [What uses it]

## Data Flow

**[Flow Name]:**

1. [Step 1]
2. [Step 2]
3. [Step 3]

**State Management:**
- [How state is handled]

## Key Abstractions

**[Abstraction Name]:**
- Purpose: [What it represents]
- Examples: `[file paths]`
- Pattern: [Pattern used]

## Entry Points

**[Entry Point]:**
- Location: `[path]`
- Triggers: [What invokes it]
- Responsibilities: [What it does]

## Error Handling

**Strategy:** [Approach]

**Patterns:**
- [Pattern 1]
- [Pattern 2]

## Cross-Cutting Concerns

**Logging:** [Approach]
**Validation:** [Approach]
**Authentication:** [Approach]

---

*Architecture analysis: [date]*

# Codebase Structure

**Analysis Date:** [YYYY-MM-DD]

## Directory Layout

## Directory Purposes

**[Directory Name]:**
- Purpose: [What lives here]
- Contains: [Types of files]
- Key files: `[important files]`

## Key File Locations

**Entry Points:**
- `[path]`: [Purpose]

**Configuration:**
- `[path]`: [Purpose]

**Core Logic:**
- `[path]`: [Purpose]

**Testing:**
- `[path]`: [Purpose]

## Naming Conventions

**Files:**
- [Pattern]: [Example]

**Directories:**
- [Pattern]: [Example]

## Where to Add New Code

**New Feature:**
- Primary code: `[path]`
- Tests: `[path]`

**New Component/Module:**
- Implementation: `[path]`

**Utilities:**
- Shared helpers: `[path]`

## Special Directories

**[Directory]:**
- Purpose: [What it contains]
- Generated: [Yes/No]
- Committed: [Yes/No]

---

*Structure analysis: [date]*

# Coding Conventions

**Analysis Date:** [YYYY-MM-DD]

## Naming Patterns

**Files:**
- [Pattern observed]

**Functions:**
- [Pattern observed]

**Variables:**
- [Pattern observed]

**Types:**
- [Pattern observed]

## Code Style

**Formatting:**
- [Tool used]
- [Key settings]

**Linting:**
- [Tool used]
- [Key rules]

## Import Organization

**Order:**
1. [First group]
2. [Second group]
3. [Third group]

**Path Aliases:**
- [Aliases used]

## Error Handling

**Patterns:**
- [How errors are handled]

## Logging

**Framework:** [Tool or "console"]

**Patterns:**
- [When/how to log]

## Comments

**When to Comment:**
- [Guidelines observed]

**JSDoc/TSDoc:**
- [Usage pattern]

## Function Design

**Size:** [Guidelines]

**Parameters:** [Pattern]

**Return Values:** [Pattern]

## Module Design

**Exports:** [Pattern]

**Barrel Files:** [Usage]

---

*Convention analysis: [date]*

# Testing Patterns

**Analysis Date:** [YYYY-MM-DD]

## Test Framework

**Runner:**
- [Framework] [Version]
- Config: `[config file]`

**Assertion Library:**
- [Library]

**Run Commands:**
```bash
[command]              # Run all tests
[command]              # Watch mode
[command]              # Coverage

[Directory pattern]

[Show actual pattern from codebase]

[Show actual mocking pattern from codebase]

[Show pattern from codebase]

[command]

[Pattern]

[Pattern]

### INTEGRATIONS.md Template

```markdown
# External Integrations

**Analysis Date:** [YYYY-MM-DD]

## APIs & External Services

**[Category]:**
- [Service] - [What it's used for]
  - SDK/Client: [package]
  - Auth: [env var name]

## Data Storage

**Databases:**
- [Type/Provider]
  - Connection: [env var]
  - Client: [ORM/client]

**File Storage:**
- [Service or "Local filesystem only"]

**Caching:**
- [Service or "None"]

## Authentication & Identity

**Auth Provider:**
- [Service or "Custom"]
  - Implementation: [approach]

## Monitoring & Observability

**Error Tracking:**
- [Service or "None"]

**Logs:**
- [Approach]

## CI/CD & Deployment

**Hosting:**
- [Platform]

**CI Pipeline:**
- [Service or "None"]

## Environment Configuration

**Required env vars:**
- [List critical vars]

**Secrets location:**
- [Where secrets are stored]

## Webhooks & Callbacks

**Incoming:**
- [Endpoints or "None"]

**Outgoing:**
- [Endpoints or "None"]

---

*Integration audit: [date]*

# Codebase Concerns

**Analysis Date:** [YYYY-MM-DD]

## Tech Debt

**[Area/Component]:**
- Issue: [What's the shortcut/workaround]
- Files: `[file paths]`
- Impact: [What breaks or degrades]
- Fix approach: [How to address it]

## Known Bugs

**[Bug description]:**
- Symptoms: [What happens]
- Files: `[file paths]`
- Trigger: [How to reproduce]
- Workaround: [If any]

## Security Considerations

**[Area]:**
- Risk: [What could go wrong]
- Files: `[file paths]`
- Current mitigation: [What's in place]
- Recommendations: [What should be added]

## Performance Bottlenecks

**[Slow operation]:**
- Problem: [What's slow]
- Files: `[file paths]`
- Cause: [Why it's slow]
- Improvement path: [How to speed up]

## Fragile Areas

**[Component/Module]:**
- Files: `[file paths]`
- Why fragile: [What makes it break easily]
- Safe modification: [How to change safely]
- Test coverage: [Gaps]

## Scaling Limits

**[Resource/System]:**
- Current capacity: [Numbers]
- Limit: [Where it breaks]
- Scaling path: [How to increase]

## Dependencies at Risk

**[Package]:**
- Risk: [What's wrong]
- Impact: [What breaks]
- Migration plan: [Alternative]

## Missing Critical Features

**[Feature gap]:**
- Problem: [What's missing]
- Blocks: [What can't be done]

## Test Coverage Gaps

**[Untested area]:**
- What's not tested: [Specific functionality]
- Files: `[file paths]`
- Risk: [What could break unnoticed]
- Priority: [High/Medium/Low]

---

*Concerns audit: [date]*