---
roadcrew_template_name: "analyze-frontend.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# Analyze Frontend Architecture

Analyze frontend architecture layers, components, routing, state management, testing structure, and detect violations.

## What This Command Does

1. Detects frontend architecture layers (Components, Pages, Layouts, Hooks, Stores)
2. Analyzes components for widget extraction potential (from analyze-multiplatform scope)
3. Detects routing framework and structure
4. Detects state management library and patterns
5. Analyzes testing structure and coverage
6. Detects frontend architectural violations
7. Generates comprehensive frontend architecture report

## Usage

Run this command when:
- Analyzing frontend architecture structure
- Planning component extraction for widgets
- Understanding routing and state management patterns
- Evaluating test coverage
- Identifying frontend violations

## Parameters

### `--repo` (optional)

Specify an external repository path to analyze:

```bash
# Analyze current directory (default)
/analyze-frontend

# Analyze external repository
/analyze-frontend --repo=/path/to/external/repo
```

## Process

### 1. Compile Detection Utilities

**⚠️ IMPORTANT: Always compile TypeScript utilities before use.**

```bash
npm run ensure-built
```

### 2. Import and Run Frontend Analysis Utilities

Import the **compiled** detection scripts from `dist/`:

```javascript
// Import from project root
import { detectFrontendLayers } from './dist/scripts/utils/roadcrew/detect-frontend-layers.js';
import { analyzeFrontendComponents } from './dist/scripts/utils/roadcrew/analyze-frontend-components.js';
import { detectFrontendRouting } from './dist/scripts/utils/roadcrew/detect-frontend-routing.js';
import { detectStateManagement } from './dist/scripts/utils/roadcrew/detect-state-management.js';
import { analyzeFrontendTesting } from './dist/scripts/utils/roadcrew/analyze-frontend-testing.js';
import { detectFrontendViolations } from './dist/scripts/utils/roadcrew/detect-frontend-violations.js';

// Default behavior - analyze current directory
const repoPath = args.repo || process.cwd();

// Run all frontend analyses
const layers = await detectFrontendLayers(repoPath);
const components = await analyzeFrontendComponents(repoPath);
const routing = await detectFrontendRouting(repoPath);
const stateManagement = await detectStateManagement(repoPath);
const testing = await analyzeFrontendTesting(repoPath);
const violations = await detectFrontendViolations(repoPath);
```

### 3. Generate Frontend Architecture Report

Create a markdown report with:

- **Architecture Layers** (Components, Pages, Layouts, Hooks, Stores)
  - Location, file count, LOC, key files
  
- **Component Analysis**
  - Total components
  - Widget extraction potential (excellent, good, possible, unlikely, not suitable)
  - Component complexity and recommendations
  
- **Routing Structure**
  - Framework (React Router, Next.js, Remix, Vue Router, etc.)
  - Pattern (file-based, config-based, mixed)
  - Route list with paths and dynamic route detection
  
- **State Management**
  - Library (Redux, Zustand, Context API, MobX, etc.)
  - Stores and patterns (global vs local)
  
- **Testing Structure**
  - Framework (Jest, Vitest, Playwright, etc.)
  - Test organization and coverage by layer
  - Components without tests (gaps)
  
- **Violations Detected**
  - Business logic in components
  - Direct API calls
  - Prop drilling
  - Missing error boundaries
  - Hardcoded configuration

### 4. Save Report

Save timestamped report to `docs/reports/` with filename `frontend-YYYY-MM-DD-HHMMSS.md`:

## Output Format

```markdown
# Frontend Architecture Analysis - YYYY-MM-DD HH:MM:SS

## Architecture Layers

### Components
- **Location:** src/components/
- **Files:** 45 files, 8,234 LOC
- **Key Files:**
  - src/components/UserCard.tsx
  - src/components/ProductList.tsx

[... other layers ...]

## Component Analysis

- **Total Components:** 45
- **Excellent Widget Potential:** 12
- **Good Widget Potential:** 8
- **Possible with Changes:** 15

[... component details ...]

## Routing Structure

- **Framework:** Next.js
- **Pattern:** file-based
- **Total Routes:** 24
- **Routes:**
  - `/` (pages/index.tsx)
  - `/users/:id` (pages/users/[id].tsx)

[... routing details ...]

## State Management

- **Library:** Redux
- **Total Stores:** 5
- **Patterns:**
  - Global: 3 stores
  - Local: 2 stores

[... state management details ...]

## Testing Structure

- **Framework:** Jest
- **Total Tests:** 32
- **Coverage:**
  - Components: 28 tested
  - Pages: 12 tested
  - Hooks: 8 tested
  - Gaps: 5 components without tests

## Violations Detected

⚠️ **8 violations found:**

1. src/components/UserProfile.tsx:45 - Business logic in component
2. src/pages/Dashboard.tsx:23 - Direct API call

[... other violations ...]
```

## Error Handling

- If detection utilities fail, show error and continue with partial results
- If repository path invalid, show error with usage examples

## Notes

- Replaces analyze-multiplatform component analysis scope
- Supports TypeScript/JavaScript React/Vue components
- All analysis utilities are atomic and can be used independently
- Reports are timestamped for historical tracking
- Can be combined with backend analysis for full-stack view