M — Map

Map is the third step of The RAMP Method. It's about building mental models of the system—and externalizing them into diagrams and documentation.

Why Map Matters

Your brain can only hold so much. Without maps:

• You forget what you learned last week
• You re-discover the same things repeatedly
• You can't explain the system to others
• You make mistakes because you missed connections

Mapping externalizes your understanding so it persists and compounds.

What to Map

1. Component Architecture

Draw the major components and how they relate:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Frontend  │────▶│   API       │────▶│  Database   │
│   (React)   │     │   (Node)    │     │  (Postgres) │
└─────────────┘     └─────────────┘     └─────────────┘
        │                  │
        │                  ▼
        │           ┌─────────────┐
        │           │   Redis     │
        │           │   (Cache)   │
        └──────────▶└─────────────┘

2. Data Flow

Trace how data moves through the system:

User Input
    │
    ▼
Form Validation (client)
    │
    ▼
API Request
    │
    ▼
Auth Middleware ──────▶ 401 Unauthorized
    │
    ▼
Business Logic
    │
    ▼
Database Write
    │
    ▼
Response to Client
    │
    ▼
UI Update

3. Request Lifecycle

Map one request end-to-end:

Step	File/Function	What Happens
1	LoginForm.tsx	User enters credentials
2	authService.login()	API call to /api/auth/login
3	authRouter.ts	Route handler receives request
4	AuthService.authenticate()	Business logic validates
5	UserRepository.findByEmail()	Database lookup
6	JwtService.sign()	Token generation
7	Response	JWT returned to client

4. Module Dependencies

Which modules depend on which:

                    ┌─────────────┐
                    │    core     │
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
   ┌───────────┐    ┌───────────┐    ┌───────────┐
   │   auth    │    │  billing  │    │   users   │
   └───────────┘    └───────────┘    └───────────┘

5. State Management

For frontend apps, map where state lives:

State Type	Location	Example
Server state	React Query cache	User data, posts
UI state	Component state	Modal open/closed
Form state	Form library	Input values
Global state	Context/Redux	Current user

How to Create Maps

Low-Tech: Paper or Whiteboard

Don't underestimate paper:

• Fast to create
• Easy to modify
• No tooling overhead

Medium-Tech: Diagramming Tools

• Excalidraw — Quick, hand-drawn style
• Mermaid — Diagrams as code (works in Markdown)
• draw.io — Free, detailed diagrams
• Lucidchart — Professional, collaborative

Mermaid Example

graph TD
    A[User] --> B[Frontend]
    B --> C[API Gateway]
    C --> D[Auth Service]
    C --> E[User Service]
    D --> F[Database]
    E --> F

High-Tech: Auto-Generated

• Ramp — AI-generated architecture docs
• Madge — JavaScript dependency graphs
• Pydeps — Python dependency graphs
• IDE — Call hierarchy, type hierarchy

When to Map

Timing	What to Map
First day	High-level component overview
First week	One feature end-to-end
First month	Major systems in depth
Ongoing	New areas as you explore

Map Formats

Quick Reference Card

A single page with the most important information:

# System Quick Reference

## Entry Points
- Frontend: src/App.tsx
- API: src/server/index.ts

## Key Directories
- /components - UI components
- /services - Business logic
- /api - API routes

## Important Files
- auth/authService.ts - Authentication
- billing/stripe.ts - Payment processing

## Commands
- npm run dev - Start development
- npm test - Run tests
- npm run deploy - Deploy to staging

Architecture Document

A longer document covering:

1. System overview
2. Component descriptions
3. Data models
4. API contracts
5. Infrastructure

Personal Knowledge Base

Ongoing notes organized by topic:

• What I learned today
• Questions and answers
• Gotchas and pitfalls
• Command cheat sheets

Using Ramp for Map

# Generate an onboarding document with architecture overview
ramp guide

# Ask for architecture explanations
ramp voice
> "Describe the overall architecture of this codebase"
> "How do the frontend and backend communicate?"
> "Create a diagram of the data flow for user registration"

After Map

Once you've built mental models, move to the final step: Practice. Apply your understanding by actually building things.

---

Related Pages

• The RAMP Method
• A — Ask
• P — Practice

---

Ready to map codebases faster? Try Ramp free →