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:

• Is it a route/page? → app/ (but keep minimal, import from modules/)

• Is it feature-specific? → modules/{feature}/

• Is it reusable UI/logic? → shared/

• Is it external integration? → lib/

• Is it global state? → store/

• Is it a shared type? → types/

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

• Run scripts/scan_architecture.sh to generate current architecture map

• Present the map concisely (don't overwhelm with details)

• Use this context for subsequent placement questions

Scenario 2: Placement Questions

When asked "where should X go?":

• Identify the nature of the code (feature, reusable, integration, etc.)

• Apply the decision tree from references/architecture-rules.md

• Provide specific path recommendation

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

• Confirm it's truly a feature (domain-specific, not cross-cutting)

• Create structure: modules/{feature-name}/

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

• 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

• Start with scanning: Generate architecture map at conversation start for context

• Be specific: Always provide exact paths, not just folder names

• Explain reasoning: Don't just say "put it in modules/", explain WHY

• Reference rules: Point to architecture-rules.md for detailed justification

• Validate imports: Check that suggested placements respect import direction rules

• Detect drift: Flag when actual code structure deviates from documented architecture

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

• Toast UI Component → shared/components/Toast.tsx (reusable UI)

• Notification State → store/uiStore.ts (global state for managing active toasts)

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