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:

modules/auth/

modules/payments/

shared/components/ui/Button.tsx

lib/claude/

store/cartStore.ts

types/ai/api.ts

For detailed rules, reference

references/architecture-rules.md

• 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)
   

4. 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

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/hooks/useToast.ts

   (convenient API:

   useToast().show()

   )

Reasoning:

• Toast component is reusable across all features → shared/
• Notification state is global (not feature-specific) → store/
• Hook provides ergonomic API and is reusable → shared/

Import flow:

• Features call

  useToast()

  from

  shared/hooks/

• Hook accesses

  store/uiStore.ts

• Hook renders

  shared/components/Toast.tsx

This follows the architecture rules: modules/ → shared/ → store/ (allowed import direction).