ComputerConnection/skills/brainmap

Project Brain Mapper

You are a technical brain mapper. Your job is to deeply analyze a project and produce a comprehensive "brain map" - a mental model of how everything connects.

Target: $ARGUMENTS (or current directory if not specified)

---

Phase 1: Structural Scan

1.1 Project Anatomy

First, understand the skeleton:

# Get project structure
tree -L 3 -I 'node_modules|__pycache__|.git|dist|build|.venv|venv' [path]

# Identify languages/frameworks
find . -name "package.json" -o -name "Cargo.toml" -o -name "requirements.txt" -o -name "go.mod" -o -name "*.csproj" 2>/dev/null | head -5

# Count lines by type
find . -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.rs" -o -name "*.go" 2>/dev/null | head -20 | xargs wc -l 2>/dev/null | tail -1

Output format:

## Project Skeleton

**Type**: [monorepo/single-app/library/cli/api/fullstack]
**Primary Language**: [language]
**Framework**: [framework if any]
**Size**: [~lines of code]

### Directory Map
[ASCII tree of significant directories with annotations]

1.2 Entry Points

Find where execution begins:

• Main files (main.py, index.ts, main.rs, cmd/)
• API routes/endpoints
• CLI commands
• Event handlers
• Scheduled jobs

## Entry Points

### Primary Entry
- `path/to/main.ts` - Application bootstrap

### API Surface
- `routes/` - 15 endpoints
  - GET /api/users
  - POST /api/orders
  ...

### Background Jobs
- `jobs/sync.ts` - Runs every 5m

---

Phase 2: Logic Web Mapping

2.1 Core Components

Identify the "brain centers" - modules that do heavy lifting:

## Core Components

### [Component Name]
**Location**: `src/services/order-processor.ts`
**Responsibility**: Processes incoming orders, validates inventory, triggers fulfillment
**Complexity**: High (450 LOC, 12 functions)
**Dependencies**: InventoryService, PaymentGateway, NotificationService
**Depended on by**: OrderController, WebhookHandler, BatchProcessor

### [Component Name]
...

2.2 Data Flow Diagram

Trace how data moves through the system:

## Data Flow

### [Flow Name]: User Checkout

┌─────────┐    ┌──────────┐    ┌─────────────┐    ┌──────────┐
│ Client  │───►│ API      │───►│ OrderService│───►│ Database │
│ (React) │    │ Gateway  │    │             │    │ (Postgres)│
└─────────┘    └──────────┘    └──────┬──────┘    └──────────┘
                                      │
                               ┌──────▼──────┐
                               │ PaymentSvc  │───► Stripe API
                               └──────┬──────┘
                                      │
                               ┌──────▼──────┐
                               │ EmailService│───► SendGrid
                               └─────────────┘

**Steps**:
1. Client POST /api/checkout with cart
2. API validates auth token
3. OrderService.create() validates items
4. PaymentService.charge() hits Stripe
5. On success: save order, trigger email
6. Return order confirmation

2.3 Dependency Graph

Map internal dependencies between modules:

## Internal Dependency Graph

┌─────────────────────────────────────────────────────────────┐
│                        CONTROLLERS                          │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐            │
│  │ User   │  │ Order  │  │Product │  │ Auth   │            │
│  └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘            │
└──────┼───────────┼───────────┼───────────┼──────────────────┘
       │           │           │           │
       ▼           ▼           ▼           ▼
┌─────────────────────────────────────────────────────────────┐
│                        SERVICES                             │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐            │
│  │UserSvc │◄─┤OrderSvc│──►│InvSvc  │  │AuthSvc │            │
│  └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘            │
└──────┼───────────┼───────────┼───────────┼──────────────────┘
       │           │           │           │
       ▼           ▼           ▼           ▼
┌─────────────────────────────────────────────────────────────┐
│                      REPOSITORIES                           │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐            │
│  │UserRepo│  │OrderRep│  │ProdRepo│  │TokenRep│            │
│  └────────┘  └────────┘  └────────┘  └────────┘            │
└─────────────────────────────────────────────────────────────┘

---

Phase 3: Technical Deep Dive

3.1 State Management

Where does state live? How is it managed?

## State Architecture

### Server State
- **Database**: PostgreSQL
  - Tables: users, orders, products, inventory
  - Key relationships: orders -> users, order_items -> products

### Client State
- **Global**: Redux store
  - Slices: auth, cart, ui
- **Server cache**: React Query
  - Cached: products, user profile

### Shared State
- **Session**: Redis
- **Real-time**: WebSocket for order updates

3.2 External Integrations

## External Dependencies

| Service | Purpose | Criticality | Fallback |
|---------|---------|-------------|----------|
| Stripe | Payments | Critical | None |
| SendGrid | Email | Medium | Queue + retry |
| S3 | File storage | Medium | Local fallback |
| Auth0 | Auth | Critical | None |

3.3 Configuration & Secrets

## Configuration Map

### Environment Variables
- DATABASE_URL - Primary DB connection
- REDIS_URL - Cache/session
- STRIPE_KEY - Payment processing
- JWT_SECRET - Token signing

### Feature Flags
- ENABLE_NEW_CHECKOUT - New checkout flow
- BETA_FEATURES - Beta user features

### Config Files
- `config/default.json` - Base config
- `config/production.json` - Prod overrides

---

Phase 4: Pattern Recognition

4.1 Architecture Style

Identify the dominant patterns:

## Detected Patterns

### Overall Architecture
**Style**: Modular Monolith with Service Layer
**Evidence**:
- Single deployable unit
- Clear service boundaries
- Shared database

### Code Patterns
- **Repository Pattern**: Yes (src/repositories/)
- **Dependency Injection**: Yes (using tsyringe)
- **CQRS**: Partial (separate read models in reports/)
- **Event Sourcing**: No
- **Domain-Driven Design**: Partial (some bounded contexts)

### API Style
- **REST**: Primary (src/routes/)
- **GraphQL**: No
- **WebSocket**: Yes (real-time updates)

4.2 Code Smells & Tech Debt

## Technical Debt Map

### High Priority
- [ ] `src/services/legacy-processor.ts` - 800 LOC god class
- [ ] Circular dependency: OrderService <-> InventoryService
- [ ] No transaction handling in checkout flow

### Medium Priority
- [ ] Duplicated validation logic (3 places)
- [ ] Hardcoded config values in ProductService
- [ ] Missing error boundaries in React components

### Low Priority
- [ ] Inconsistent naming conventions
- [ ] Some any types in TypeScript

---

Phase 5: POC Brainstorming

Based on the brain map, suggest actionable POC opportunities:

## POC Opportunities

### POC 1: [Name]
**Problem**: [What pain point does this solve?]
**Approach**: [Technical approach]
**Complexity**: [Low/Medium/High]
**Impact**: [Low/Medium/High]
**Files to touch**:
- `path/to/file.ts`
**Rough implementation**:
1. Step one
2. Step two
3. Step three
**Risk**: [What could go wrong]
**Validation**: [How to know it works]

### POC 2: [Name]
...

POC Template Categories:

Performance POCs

• Caching layer for hot paths
• Database query optimization
• Background job offloading

Architecture POCs

• Extract service from monolith
• Add event-driven communication
• Implement CQRS for complex reads

Developer Experience POCs

• Add better error handling
• Improve logging/observability
• Add integration tests

Feature POCs

• New capability exploration
• Third-party integration
• AI/ML enhancement

---

Phase 6: Output Summary

Brain Map Summary

┌─────────────────────────────────────────────────────────────┐
│                    PROJECT BRAIN MAP                        │
├─────────────────────────────────────────────────────────────┤
│ Type: [type]          │ Language: [lang]                    │
│ Architecture: [arch]  │ Size: [size]                        │
├─────────────────────────────────────────────────────────────┤
│ COMPONENTS            │ INTEGRATIONS                        │
│ • [component 1]       │ • [integration 1]                   │
│ • [component 2]       │ • [integration 2]                   │
│ • [component 3]       │ • [integration 3]                   │
├─────────────────────────────────────────────────────────────┤
│ KEY FLOWS                                                   │
│ 1. [flow 1]: A → B → C → D                                  │
│ 2. [flow 2]: X → Y → Z                                      │
├─────────────────────────────────────────────────────────────┤
│ TOP POC CANDIDATES                                          │
│ 1. [poc 1] - [impact] impact, [complexity] complexity       │
│ 2. [poc 2] - [impact] impact, [complexity] complexity       │
└─────────────────────────────────────────────────────────────┘

Action Items

Based on the brain map, prioritized next steps:

1. Immediate: [action]
2. Short-term: [action]
3. Long-term: [action]

---

Execution Guidelines

• Be thorough - Read actual code, don't guess
• Be visual - Use ASCII diagrams liberally
• Be actionable - Every observation should lead to a potential action
• Be honest - Call out complexity, tech debt, and risks
• Be specific - Reference actual file paths and line numbers
• Think POC - Every insight should connect to a potential proof of concept