---
roadcrew_template_name: "analyze-backend.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 Backend Architecture

Analyze backend architecture layers, APIs, MCP tools, and detect architectural violations.

## What This Command Does

1. Detects backend architecture layers (Data, Business Logic, API, MCP)
2. Analyzes REST and GraphQL API endpoints
3. Analyzes MCP (Model Context Protocol) architecture
4. Detects backend architectural violations
5. Generates comprehensive backend architecture report

## Usage

Run this command when:
- Analyzing backend architecture structure
- Identifying architectural violations
- Understanding API endpoint organization
- Evaluating MCP tool architecture
- Planning backend refactoring

## Parameters

### `--repo` (optional)

Specify an external repository path to analyze:

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

# Analyze external repository
/analyze-backend --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 Backend Analysis Utilities

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

```javascript
// Import from project root
import { detectBackendLayers } from './dist/scripts/utils/roadcrew/detect-backend-layers.js';
import { analyzeAPIs } from './dist/scripts/utils/roadcrew/analyze-apis.js';
import { analyzeMCPArchitecture } from './dist/scripts/utils/roadcrew/analyze-mcp-architecture.js';
import { detectBackendViolations } from './dist/scripts/utils/roadcrew/detect-backend-violations.js';

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

// Run all backend analyses
const layers = await detectBackendLayers(repoPath);
const apis = await analyzeAPIs(repoPath);
const mcp = await analyzeMCPArchitecture(repoPath);
const violations = await detectBackendViolations(repoPath);
```

### 3. Generate Backend Architecture Report

Create a markdown report with:

- **Architecture Layers** (Data, Business Logic, API, MCP)
  - Location, file count, LOC, technologies, key files
  
- **API Analysis**
  - REST endpoints (method, path, file, line)
  - GraphQL schemas (queries, mutations, types)
  - Framework detection (Express, Fastify, Flask, etc.)
  - API patterns (RESTful, RPC-style, Mixed)
  
- **MCP Architecture**
  - Tools defined
  - Server configuration
  - Tool-to-service mappings
  
- **Violations Detected**
  - Cross-layer violations (DB in controllers, SQL in routes, etc.)
  - Severity levels (critical, warning, info)
  - Recommendations for fixes

### 4. Save Report

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

## Output Format

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

## Architecture Layers

### Data Layer
- **Location:** src/models/, src/repositories/
- **Files:** 15 files, 2,341 LOC
- **Technologies:** Prisma, PostgreSQL
- **Key Files:**
  - src/models/user.model.ts
  - src/repositories/user.repository.ts

[... other layers ...]

## API Analysis

- **Total Endpoints:** 42
- **Framework:** Express.js
- **Pattern:** RESTful
- **REST Endpoints:** 40
- **GraphQL Schemas:** 2

[... endpoint details ...]

## MCP Architecture

- **Total Tools:** 12
- **Server Configs:** 1
- **Technologies:** MCP SDK, TypeScript/JavaScript

[... tool details ...]

## Violations Detected

⚠️ **3 cross-layer violations found:**

1. src/controllers/user.controller.ts:45 - Direct database import
   - **Issue:** Controller imports Prisma directly
   - **Recommendation:** Move database access to repository/service layer

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

## Error Handling

- If detection utilities fail, show error and continue with partial results
- If config files don't exist, create them with detected values
- If repository path invalid, show error with usage examples

## Example Workflows

### Scenario 1: Analyze Current Repository

```bash
/analyze-backend
```

### Scenario 2: Analyze External Repository

```bash
/analyze-backend --repo=../saas-starter-kit
```

## Notes

- Supports TypeScript/JavaScript and Python file patterns
- All analysis utilities are atomic and can be used independently
- Reports are timestamped for historical tracking
- Can be combined with frontend analysis for full-stack view