---
roadcrew_template_name: "analyze-architecture-full.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 Architecture (Full)

Comprehensive architecture analysis combining frontend, backend, dependencies, extension points, and testing structure.

## What This Command Does

1. Analyzes backend architecture (layers, APIs, MCP, violations)
2. Analyzes frontend architecture (layers, components, routing, state, testing, violations)
3. Analyzes dependencies (circular dependencies, cross-layer imports)
4. Detects extension points (config files, customizable markers, plugins)
5. Analyzes testing structure (organization, coverage, gaps)
6. Generates comprehensive full-stack architecture report in `docs/reports/architecture/` with name `architecture-YYYY-MM-DD-HHMMSS.md`
7. Updates project `README.md` with architecture analysis section linking to the report

## Usage

Run this command when:
- Performing complete architecture analysis
- Understanding full-stack architecture
- Planning major refactoring
- Evaluating architectural health

## Parameters

### `--repo` (optional)

Specify an external repository path to analyze:

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

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

## Process

### 1. Compile Detection Utilities

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

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

### 2. Run All Architecture Analyses

This command calls all atomic analysis utilities:

**Backend Analysis:**
- `detect-backend-layers` - Identifies backend architectural layers
- `analyze-apis` - Maps and analyzes API endpoints
- `analyze-mcp-architecture` - Analyzes MCP tool structure
- `detect-backend-violations` - Detects architectural violations

**Frontend Analysis:**
- `detect-frontend-layers` - Identifies frontend architectural layers
- `analyze-frontend-components` - Analyzes component structure and complexity
- `detect-frontend-routing` - Maps routing architecture
- `detect-state-management` - Identifies state management patterns
- `analyze-frontend-testing` - Analyzes test structure and coverage
- `detect-frontend-violations` - Detects architectural violations

**Shared Analysis:**
- `analyze-dependencies` - Detects circular and cross-layer dependencies
- `detect-extension-points` - Finds configuration and plugin extension points
- `analyze-testing-structure` - Comprehensive testing analysis

### 3. Generate Comprehensive Report

Creates a complete architecture report combining all analyses.

### 4. Save Report

Save timestamped report to `docs/reports/`:

**Filename:** `architecture-YYYY-MM-DD-HHMMSS.md`

## Output Format

The comprehensive report includes:

- **Backend Architecture** (from analyze-backend)
- **Frontend Architecture** (from analyze-frontend)
- **Dependencies Analysis** (circular, cross-layer)
- **Extension Points** (config, markers, plugins)
- **Testing Structure** (organization, coverage)
- **Summary & Recommendations**

## Automatic Documentation Updates

After analysis completes, the command automatically audits and updates the following documentation files:

### Project Root Files
- `README.md` — Comprehensive update with architecture overview, tech stack, component layers, and key features

### Memory Bank Files
- `memory-bank/systemPatterns.md` — System architecture and design patterns
- `memory-bank/techContext.md` — Technology stack and dependencies
- `memory-bank/progress.md` — Status and component inventory

### Cursor Rules Files
- `.cursor/rules/06-testing.mdc` — Testing standards and TDD practices
- `.cursor/rules/04-coding-standards.mdc` — Code quality standards
- `.cursor/rules/07-project-patterns.mdc` — Project-specific patterns and workflows

**Update Logic:**
- Verifies consistency between analysis report and documentation
- Updates timestamps to reflect analysis date
- Performs surgical section updates (preserves unaffected content)
- Thoroughly updates README with detailed architecture sections:
  - System architecture overview
  - Backend layers and components
  - Frontend layers and components
  - Key dependencies
  - Testing structure and coverage
  - Extension points and customization
- Reports audit results including what was verified and what needs attention

## Notes

- Combines all architecture analysis capabilities in one command
- Can be run independently or alongside individual frontend/backend analyses
- All atomic scripts can also be used independently for targeted analysis