architecture-navigator

Architecture Navigator

Overview

Provide instant architecture intelligence for the DevPrep AI codebase. Generate architecture maps, answer placement questions ("where should X go?"), and validate code organization against the 7-folder structure. This skill eliminates the need to manually read architecture documentation at conversation start.

Core Capabilities

1. Architecture Scanning

When starting a development conversation or when explicitly requested, scan the codebase to generate a real-time architecture map.

How to scan:

# Run the architecture scanner from project root
bash ./.claude/skills/architecture-navigator/scripts/scan_architecture.sh

The scanner will output:

• 7-Folder Structure: modules/, shared/, lib/, store/, types/, styles/, app/
• Module List: All feature modules with file counts
• Key Locations: API layer, state management, UI components
• Quick Stats: Total files, module count, component count

When to scan:

• At the start of development conversations about architecture
• When asked "what modules exist?" or "what's the structure?"
• Before suggesting where new code should go
• When validating architecture compliance

Output format: Compact markdown summary (~50-100 lines) showing the current architecture state.

2. Interactive Placement Queries

Answer "where should X go?" questions using the 7-folder placement rules.

Decision tree:

1. Is it a route/page? → app/ (but keep minimal, import from modules/)
2. Is it feature-specific? → modules/{feature}/
3. Is it reusable UI/logic? → shared/
4. Is it external integration? → lib/
5. Is it global state? → store/
6. Is it a shared type? → types/
7. Is it pure styling? → styles/

Example queries and responses:

| User Query | Response | |------------|----------| | "Where should social login go?" | modules/auth/ - Feature-specific authentication logic | | "Where should I add payment processing?" | modules/payments/ - New feature module for payment domain logic | | "Where do reusable buttons go?" | shared/components/ui/Button.tsx - Reusable UI component | | "Where's the Claude AI integration?" | lib/claude/ - External service integration | | "Where should shopping cart state go?" | store/cartStore.ts - Global state management | | "Where do API types go?" | types/ai/api.ts - Shared TypeScript definitions |

For detailed rules, reference references/architecture-rules.md which includes:

• Complete placement rules for all 7 folders
• Import direction rules (what can import what)
• Forbidden patterns (circular dependencies, wrong imports)
• Decision tree for complex placement questions
• Common examples and edge cases

3. Module Discovery

List existing modules and explain their purpose when asked.

How to discover modules:

# Quick module list
ls -1 frontend/src/modules/

# With file counts
find frontend/src/modules/ -mindepth 1 -maxdepth 1 -type d -exec sh -c 'echo -n "{}:" && find "{}" -name "*.ts*" | wc -l' \;

Common questions:

• "What modules exist?" → Run module discovery
• "Where does authentication live?" → Check modules/ for auth-related folders
• "What features are implemented?" → Scan modules/ directory

4. Architecture Validation

Validate that code follows the 7-folder structure rules.

What to check:

• ✅ Routes in app/ are minimal (just imports)
• ✅ Business logic is in modules/, not app/
• ✅ Shared components are in shared/, not duplicated
• ✅ External integrations are in lib/
• ✅ Global state is in store/
• ✅ Imports follow allowed directions (see architecture-rules.md)

Validation commands:

# Check for business logic in app/ (should be minimal)
grep -r "useState\|useEffect\|async function" frontend/src/app/

# Check for cross-module imports (forbidden)
grep -r "from.*modules/" frontend/src/modules/

# Check for modules importing from shared (allowed)
grep -r "from.*shared/" frontend/src/modules/

Workflow: Using This Skill

Scenario 1: Conversation Start

When a development conversation begins, proactively scan the architecture:

1. Run scripts/scan_architecture.sh to generate current architecture map
2. Present the map concisely (don't overwhelm with details)
3. Use this context for subsequent placement questions

Scenario 2: Placement Questions

When asked "where should X go?":

1. Identify the nature of the code (feature, reusable, integration, etc.)
2. Apply the decision tree from references/architecture-rules.md
3. Provide specific path recommendation
4. Explain WHY (which rule applies)

Example:

User: "Where should I add OAuth authentication?"

Response:
OAuth authentication should go in `modules/auth/oauth/`:
- It's feature-specific (authentication domain)
- It belongs in modules/ (not reusable across other features)
- Structure: modules/auth/oauth/GoogleAuth.tsx, OAuthProvider.tsx, etc.

The OAuth client setup (SDK wrapper) should go in `lib/oauth/client.ts` (external integration).

Scenario 3: New Feature Module

When creating a new feature module:

1. Confirm it's truly a feature (domain-specific, not cross-cutting)
2. Create structure: modules/{feature-name}/
3. Recommend typical structure:

`` modules/{feature}/ ├── components/ - Feature-specific UI ├── hooks/ - Feature-specific hooks ├── utils/ - Feature-specific utilities └── types.ts - Feature-specific types (if not shared) ``

1. Remind about import rules (can import from shared/, lib/, store/, types/)

Auto-Trigger Keywords

This skill automatically activates when these phrases are detected:

• "where should"
• "add module"
• "architecture"
• "structure"
• "organize"
• "place code"
• "what modules"
• "where does [X] live"
• "where's the API"
• "folder structure"

Manual invocation: Use /architecture or explicitly request "scan the architecture".

Resources

scripts/scan_architecture.sh

Fast bash script that scans the 7-folder structure and generates a markdown architecture map. Outputs module list, key locations, and quick stats.

Usage:

bash scripts/scan_architecture.sh [project-root]

Output: Compact markdown summary (~50-100 lines) suitable for loading into context.

references/architecture-rules.md

Comprehensive placement rules for the 7-folder architecture. Reference this document when:

• Answering complex placement questions
• Validating architecture compliance
• Explaining import direction rules
• Handling edge cases or ambiguous scenarios

Key sections:

• 7-Folder structure overview
• Detailed placement rules for each folder
• Import direction rules (what can import what)
• Forbidden patterns
• Decision tree for placement
• Common examples table

Best Practices

1. Start with scanning: Generate architecture map at conversation start for context
2. Be specific: Always provide exact paths, not just folder names
3. Explain reasoning: Don't just say "put it in modules/", explain WHY
4. Reference rules: Point to architecture-rules.md for detailed justification
5. Validate imports: Check that suggested placements respect import direction rules
6. Detect drift: Flag when actual code structure deviates from documented architecture
7. Keep it concise: Architecture maps should be scannable (~50-100 lines)

Example Usage

User: "I want to add a notification system that shows toast messages across the app."

Response:

Let me scan the current architecture first:

bash ./.claude/skills/architecture-navigator/scripts/scan_architecture.sh

[Architecture map output]

For a global notification system with toast messages:

1. Toast UI Component → shared/components/Toast.tsx (reusable UI)
2. Notification State → store/uiStore.ts (global state for managing active toasts)
3. Toast Hook → `shared/