7.1 KiB
7.1 KiB
name, description, nextStepFile
| name | description | nextStepFile |
|---|---|---|
| step-03-map-architecture | Build a detailed map of components, data flow, dependencies, and patterns as the analytical core of the workflow | ./step-04-document-findings.md |
Step 3: Map Architecture
STEP GOAL:
Build a detailed map of components, data flow, dependencies, and patterns. This is the analytical core of the workflow.
MANDATORY EXECUTION RULES (READ FIRST):
Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config
{communication_language}
Role Reinforcement:
- ✅ You are an Implementation Partner guiding structured development activities
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
- ✅ Maintain clear and structured tone throughout
Step-Specific Rules:
- 🎯 Focus only on mapping components, tracing data flows, identifying layers, integrations, state, dependencies, and patterns
- 🚫 FORBIDDEN to begin writing the final architecture document — that is the next step
- 💬 Approach: Deep dive into codebase structure with user, tracing flows and mapping dependencies collaboratively
- 📋 Use the scan observations from Step 2 as your starting point
EXECUTION PROTOCOLS:
- 🎯 Create comprehensive component inventory, data flow traces, and dependency maps
- 💾 Document component map, data flows, layers, integrations, state management, dependencies, and patterns
- 📖 Reference scan results from Step 2 and original questions from Step 1
- 🚫 Do not write the final document yet — focus on raw analysis
CONTEXT BOUNDARIES:
- Available context: Analysis question and scope from Step 1; scan observations from Step 2
- Focus: Deep architectural analysis — components, flows, dependencies, patterns
- Limits: No final document writing — raw analysis only
- Dependencies: Steps 1 and 2 must be complete
Sequence of Instructions (Do not deviate, skip, or optimize)
1. Map Component and Module Structure
For each major module or component area:
- What is its responsibility?
- What does it expose (public API, exports)?
- What does it encapsulate (internal details)?
- How large is it (files, lines, complexity)?
Create a component inventory:
Components:
- AuthModule — Handles login, registration, session management
- UserService — CRUD operations for user profiles
- PaymentGateway — Stripe integration, invoice generation
- NotificationService — Email + push notifications
- ...
2. Trace Data Flow
Pick 2-3 key user actions and trace data from start to finish:
- User action (click, form submit, page load)
- Frontend handling (event handler, state update, API call)
- API layer (route, middleware, validation)
- Business logic (service, domain logic, transformations)
- Data layer (database query, cache, external API)
- Response path (back through layers to UI)
Document at least one complete flow end-to-end.
3. Identify Layers
Determine the architectural layers and their boundaries:
| Layer | Purpose | Location |
|---|---|---|
| Presentation | UI rendering, user interaction | src/components/, src/pages/ |
| Application | Use cases, orchestration | src/services/, src/hooks/ |
| Domain | Business rules, entities | src/models/, src/domain/ |
| Infrastructure | Database, external APIs, file system | src/db/, src/integrations/ |
Note: Not all codebases have clean layers. Document what you actually find, including layer violations.
4. Map External Integrations
List every external system the codebase talks to:
| Integration | Purpose | Protocol | Location in Code |
|---|---|---|---|
| PostgreSQL | Primary data store | SQL via ORM | src/db/ |
| Stripe | Payment processing | REST API | src/payments/ |
| SendGrid | Email delivery | REST API | src/notifications/ |
| Redis | Caching, sessions | Redis protocol | src/cache/ |
5. Document State Management
How does the application manage state?
- Frontend: Global store (Redux, Zustand), context, local state, URL state
- Backend: Session storage, database, cache, in-memory
- Shared: How does state sync between client and server?
6. Create Dependency Graph
Map which modules depend on which:
- Identify core modules that many things depend on (high fan-in)
- Identify modules that depend on many things (high fan-out)
- Look for circular dependencies
- Note tightly coupled vs loosely coupled areas
7. Identify Architectural Patterns
Document patterns you observe:
- Structural: MVC, MVVM, Clean Architecture, Hexagonal, Monolith, Microservices
- Data: Repository pattern, Active Record, Data Mapper, CQRS
- Communication: REST, GraphQL, WebSocket, Event-driven, Message queue
- Error handling: Centralized, per-module, try-catch patterns, error boundaries
- Testing: Unit/integration/e2e split, mocking approach, test data strategy
8. Verify Checklist
- Component/module inventory created
- At least one data flow traced end-to-end
- Architectural layers identified
- External integrations mapped
- State management approach documented
- Key dependencies mapped (especially high fan-in/fan-out)
- Architectural patterns identified
9. Present MENU OPTIONS
Display: "Select an Option: [C] Continue to Step 4: Document Findings"
Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- User can chat or ask questions - always respond and then redisplay menu options
CRITICAL STEP COMPLETION NOTE
ONLY WHEN the architectural mapping is complete with components, flows, and dependencies documented will you then load and read fully {nextStepFile} to execute.
🚨 SYSTEM SUCCESS/FAILURE METRICS
✅ SUCCESS:
- Component/module inventory created
- At least one data flow traced end-to-end
- Architectural layers identified
- External integrations mapped
- State management approach documented
- Key dependencies mapped (especially high fan-in/fan-out)
- Architectural patterns identified
❌ SYSTEM FAILURE:
- Skipping data flow tracing
- Not mapping external integrations
- Beginning final document creation before analysis is complete
- Ignoring dependency relationships
Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.