Repository Analyzer

Repository Analyzer

Purpose

Quickly understand unfamiliar codebases by automatically scanning structure, detecting technologies, mapping dependencies, and generating comprehensive documentation.

For SDAM users: Creates external documentation of codebase structure you can reference later. For ADHD users: Instant overview without manual exploration - saves hours of context-switching. For all users: Onboard to new projects in minutes instead of days.

Activation Triggers

• User says: "analyze repository", "understand codebase", "document project"
• Requests for: "what's in this repo", "how does this work", "codebase overview"
• New project onboarding scenarios
• Technical debt assessment requests

Core Workflow

1. Scan Repository Structure

Step 1: Get directory structure

# Use filesystem tools to map structure
tree -L 3 -I 'node_modules|.git|dist|build'

Step 2: Count files by type

# Identify languages used
find . -type f -name "*.js" | wc -l
find . -type f -name "*.py" | wc -l
find . -type f -name "*.go" | wc -l
# etc...

Step 3: Measure codebase size

# Count lines of code
cloc . --exclude-dir=node_modules,.git,dist,build

2. Detect Technologies

Languages: JavaScript, TypeScript, Python, Go, Rust, Java, etc.

Frameworks:

• Frontend: React, Vue, Angular, Svelte
• Backend: Express, FastAPI, Django, Rails
• Mobile: React Native, Flutter
• Desktop: Electron, Tauri

Detection methods:

const detectFramework = async () => {
  // Check package.json
  const packageJson = await readFile('package.json');
  const dependencies = packageJson.dependencies || {};

  if ('react' in dependencies) return 'React';
  if ('vue' in dependencies) return 'Vue';
  if ('express' in dependencies) return 'Express';

  // Check requirements.txt
  const requirements = await readFile('requirements.txt');
  if (requirements.includes('fastapi')) return 'FastAPI';
  if (requirements.includes('django')) return 'Django';

  // Check go.mod
  const goMod = await readFile('go.mod');
  if (goMod.includes('gin-gonic')) return 'Gin';

  return 'Unknown';
};

3. Map Dependencies

For Node.js:

# Read package.json
cat package.json | jq '.dependencies'
cat package.json | jq '.devDependencies'

# Check for outdated packages
npm outdated

For Python:

# Read requirements.txt or pyproject.toml
cat requirements.txt

# Check for outdated packages
pip list --outdated

For Go:

# Read go.mod
cat go.mod

# Check for outdated modules
go list -u -m all

4. Identify Architecture Patterns

Common patterns to detect:

• MVC (Model-View-Controller): models/, views/, controllers/
• Layered: api/, services/, repositories/
• Feature-based: features/auth/, features/users/
• Domain-driven: domain/, application/, infrastructure/
• Microservices: Multiple services in services/ directory
• Monorepo: Workspaces or packages structure

Detection logic:

const detectArchitecture = (structure) => {
  if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
    return 'MVC Pattern';
  }
  if (structure.includes('features')) {
    return 'Feature-based Architecture';
  }
  if (structure.includes('domain') && structure.includes('application')) {
    return 'Domain-Driven Design';
  }
  if (structure.includes('services') && structure.includes('api-gateway')) {
    return 'Microservices Architecture';
  }
  return 'Custom Architecture';
};

5. Extract Technical Debt

Search for indicators:

# Find TODOs
grep -r "TODO" --include="*.js" --include="*.py" --include="*.go"

# Find FIXMEs
grep -r "FIXME" --include="*.js" --include="*.py" --include="*.go"

# Find HACKs
grep -r "HACK" --include="*.js" --include="*.py" --include="*.go"

# Find deprecated code
grep -r "@deprecated" --include="*.js" --include="*.ts"

Complexity analysis:

// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
  // Functions > 50 lines = high complexity
  // Functions > 100 lines = very high complexity
  // Cyclomatic complexity > 10 = needs refactoring
};

6. Generate Documentation

Output format:

# {Project Name} - Repository Analysis

**Generated:** {timestamp}
**Analyzed by:** Claude Code Repository Analyzer

---

## 📊 Overview

**Primary Language:** {language}
**Framework:** {framework}
**Architecture:** {architecture pattern}
**Total Files:** {count}
**Lines of Code:** {LOC}
**Last Updated:** {git log date}

---

## 📁 Directory Structure

project/ ├── src/ │ ├── components/ │ ├── services/ │ └── utils/ ├── tests/ └── docs/

---

## 🛠 Technologies

### Frontend
- React 18.2.0
- TypeScript 5.0
- Tailwind CSS 3.3

### Backend
- Node.js 18
- Express 4.18
- PostgreSQL 15

### DevOps
- Docker
- GitHub Actions
- Jest for testing

---

## 📦 Dependencies

### Production (12 packages)
- express: 4.18.2
- pg: 8.11.0
- jsonwebtoken: 9.0.0
- ...

### Development (8 packages)
- typescript: 5.0.4
- jest: 29.5.0
- eslint: 8.40.0
- ...

### ⚠️ Outdated (3 packages)
- express: 4.18.2 → 4.19.0 (minor update available)
- jest: 29.5.0 → 29.7.0 (patch updates available)

---

## 🏗 Architecture

**Pattern:** Layered Architecture

**Layers:**
1. **API Layer** (`src/api/`): REST endpoints, request validation
2. **Service Layer** (`src/services/`): Business logic
3. **Repository Layer** (`src/repositories/`): Database access
4. **Models** (`src/models/`): Data structures

**Data Flow:**

Client → API → Service → Repository → Database

---

## 🔍 Code Quality

**Metrics:**
- Average function length: 25 lines
- Cyclomatic complexity: 3.2 (low)
- Test coverage: 78%
- TypeScript strict mode: ✅ Enabled

**Strengths:**
- ✅ Well-structured codebase
- ✅ Good test coverage
- ✅ Type-safe with TypeScript

**Areas for Improvement:**
- ⚠️ 12 TODOs found (see Technical Debt section)
- ⚠️ 3 outdated dependencies
- ⚠️ Missing documentation in `/utils`

---

## 🐛 Technical Debt

### High Priority (3)
- **FIXME** in `src/services/auth.js:42`: JWT refresh token rotation not implemented
- **TODO** in `src/api/users.js:78`: Add rate limiting
- **HACK** in `src/utils/cache.js:23`: Using setTimeout instead of proper cache expiry

### Medium Priority (5)
- **TODO** in `src/components/Dashboard.jsx:15`: Optimize re-renders
- **TODO** in `tests/integration/api.test.js:100`: Add more edge cases
- ...

### Low Priority (4)
- **TODO** in `README.md:50`: Update installation instructions
- ...

---

## 🚀 Entry Points

**Main Application:**
- `src/index.js` - Server entry point
- `src/client/index.jsx` - Client entry point

**Development:**
- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run build` - Production build

**Configuration:**
- `.env.example` - Environment variables
- `tsconfig.json` - TypeScript config
- `jest.config.js` - Test configuration

---

## 📋 Common Tasks

**Adding a new feature:**
1. Create component in `src/components/`
2. Add service logic in `src/services/`
3. Create API endpoint in `src/api/`
4. Write tests in `tests/`

**Database changes:**
1. Create migration in `migrations/`
2. Update models in `src/models/`
3. Run `npm run migrate`

---

## 🔗 Integration Points

**External Services:**
- PostgreSQL database (port 5432)
- Redis cache (port 6379)
- SendGrid API (email)
- Stripe API (payments)

**API Endpoints:**
- `GET /api/users` - List users
- `POST /api/auth/login` - Authentication
- `GET /api/dashboard` - Dashboard data

---

## 📚 Additional Resources

- [Architecture Diagram](./docs/architecture.png)
- [API Documentation](./docs/api.md)
- [Development Guide](./docs/development.md)

---

**Next Steps:**
1. Address high-priority technical debt
2. Update outdated dependencies
3. Increase test coverage to 85%+
4. Document utility functions

See patterns.md for architecture pattern library and examples.md for analysis examples.

Advanced Analysis Features

Git History Analysis

# Find most changed files (hotspots)
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10

# Find largest contributors
git shortlog -sn

# Recent activity
git log --oneline --since="30 days ago" --no-merges

Code Complexity Metrics

# Using complexity tools
npx eslint src/ --format json | jq '.[] | select(.messages[].ruleId == "complexity")'

# Or manual analysis
# Functions > 50 lines = candidate for refactoring
# Files > 500 lines = candidate for splitting

Dependency Security

# Check for vulnerabilities
npm audit
pip-audit  # for Python
go mod tidy && go list -m all  # for Go

Integration with Other Skills

Context Manager

Save repository overview:

remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
         12 high-priority TODOs, 78% test coverage

Error Debugger

If analysis finds common issues:

Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected

Browser App Creator

Generate visualization:

Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart

Quality Checklist

Before delivering documentation, verify:

• ✅ Directory structure mapped
• ✅ Languages and frameworks identified
• ✅ Dependencies listed
• ✅ Architecture pattern detected
• ✅ Technical debt catalogued
• ✅ Entry points documented
• ✅ Common tasks explained
• ✅ Markdown formatted properly

Output Delivery

Format: Markdown file saved to ~/.claude-artifacts/analysis-{project}-{timestamp}.md (Linux/macOS) or %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md (Windows)

Notify user:

✅ **{Project Name} Analysis** complete!

**Summary:**
- {LOC} lines of code across {file_count} files
- Primary stack: {stack}
- Architecture: {pattern}
- {todo_count} TODOs found

**Documentation saved to:** {filepath}

**Key findings:**
1. {finding_1}
2. {finding_2}
3. {finding_3}

**Recommended actions:**
- {action_1}
- {action_2}

Common Analysis Scenarios

New Project Onboarding

User joins unfamiliar project → analyzer provides complete overview in minutes

Technical Debt Assessment

User needs to evaluate legacy code → analyzer identifies all TODOs/FIXMEs/HACKs

Dependency Audit

User wants to check outdated packages → analyzer lists all outdated dependencies with versions

Architecture Documentation

User needs to document existing project → analyzer generates comprehensive architecture docs

Success Criteria

✅ Complete codebase structure mapped ✅ All technologies identified correctly ✅ Dependencies catalogued with versions ✅ Architecture pattern detected ✅ Technical debt surfaced ✅ Documentation generated in <2 minutes ✅ Markdown output saved to artifacts ✅ Actionable recommendations provided

Additional Resources

• [Pattern Library](patterns.md) - Common architecture patterns
• [Analysis Examples](examples.md) - Real-world repository analyses

Quick Reference

Trigger Phrases

• "analyze repository"
• "understand codebase"
• "document project"
• "what's in this repo"
• "codebase overview"
• "technical debt report"

Output Location

• Linux/macOS: ~/.claude-artifacts/analysis-{project}-{timestamp}.md
• Windows: %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

Analysis Depth Options

• Quick (<1 min): Structure + languages only
• Standard (1-2 min): + dependencies + patterns
• Deep (3-5 min): + git history + complexity metrics + security audit

Repository Analysis Examples

Real-world examples of repository analysis across different project types.

Example 1: React + Express Full-Stack App

User Request

"Analyze this codebase - I just inherited it and need to understand what's here."

Analysis Output

# TaskManager - Repository Analysis

**Generated:** 2025-10-17 20:15:23
**Analyzed by:** Claude Code Repository Analyzer

---

## 📊 Overview

**Primary Language:** JavaScript (78%), TypeScript (22%)
**Framework:** React (frontend) + Express (backend)
**Architecture:** Layered Architecture with Feature-Based Frontend
**Total Files:** 147 files
**Lines of Code:** 12,450 LOC
**Last Updated:** 2 days ago

---

## 📁 Directory Structure

taskmanager/ ├── client/ # React frontend │ ├── src/ │ │ ├── features/ # Feature-based components │ │ │ ├── auth/ │ │ │ ├── tasks/ │ │ │ └── dashboard/ │ │ ├── shared/ # Shared utilities │ │ └── App.jsx │ └── package.json ├── server/ # Express backend │ ├── src/ │ │ ├── api/ # Routes & controllers │ │ ├── services/ # Business logic │ │ ├── repositories/ # Database access │ │ └── models/ # Data structures │ └── package.json ├── database/ │ └── migrations/ └── docker-compose.yml

---

## 🛠 Technologies

### Frontend
- React 18.2.0
- React Router 6.14.0
- Axios 1.4.0
- Tailwind CSS 3.3.3

### Backend
- Node.js 18.16.0
- Express 4.18.2
- PostgreSQL 15 (via pg 8.11.0)
- JWT authentication (jsonwebtoken 9.0.1)

### DevOps
- Docker & Docker Compose
- GitHub Actions CI/CD
- Jest (testing) - 29.6.1

---

## 📦 Dependencies

### Production Dependencies
**Frontend (12 packages):**
- react: 18.2.0
- react-router-dom: 6.14.0
- axios: 1.4.0
- tailwindcss: 3.3.3

**Backend (8 packages):**
- express: 4.18.2
- pg: 8.11.0
- jsonwebtoken: 9.0.1
- bcrypt: 5.1.0

### ⚠️ Outdated Packages (3)
- express: 4.18.2 → 4.19.0 (security patch available)
- axios: 1.4.0 → 1.5.1 (patch update)
- jest: 29.6.1 → 29.7.0 (patch update)

**Recommendation:** Run `npm update` in both client/ and server/

---

## 🏗 Architecture

**Pattern:** Layered Architecture (backend) + Feature-Based (frontend)

### Backend Layers
1. **API Layer** (`server/src/api/`): REST endpoints, request validation
2. **Service Layer** (`server/src/services/`): Business logic, authorization
3. **Repository Layer** (`server/src/repositories/`): Database queries
4. **Models** (`server/src/models/`): Data structures & validation

### Frontend Features
- **auth/**: Login, register, password reset
- **tasks/**: Create, edit, delete tasks
- **dashboard/**: Overview, analytics

**Data Flow:**

Client (React) → API (Express) → Service → Repository → PostgreSQL

---

## 🔍 Code Quality

**Metrics:**
- Average function length: 28 lines
- Cyclomatic complexity: 3.8 (low-medium)
- Test coverage: 65% (backend), 42% (frontend)
- Files > 200 lines: 8 (potential refactor targets)

**Strengths:**
- ✅ Clear separation of concerns (layered architecture)
- ✅ Feature-based frontend (easy to navigate)
- ✅ Authentication implemented with JWT
- ✅ Database migrations in place

**Areas for Improvement:**
- ⚠️ Low frontend test coverage (42%)
- ⚠️ No API documentation (consider Swagger/OpenAPI)
- ⚠️ Large component files in `dashboard/` (>300 lines)
- ⚠️ Missing error handling in some API routes

---

## 🐛 Technical Debt

### High Priority (5)
1. **FIXME** in `server/src/services/task.service.js:67`

// FIXME: This query is slow for users with 1000+ tasks // Need to add pagination and indexing

2. **TODO** in `server/src/api/auth.controller.js:45`

// TODO: Implement refresh token rotation for better security

3. **HACK** in `client/src/features/tasks/TaskList.jsx:123`

// HACK: Force re-render to fix stale data issue // Should use proper state management instead

4. **Security Issue** in `server/src/api/tasks.routes.js`
   - Missing rate limiting on POST endpoints
   - Vulnerable to brute force attacks

5. **Performance Issue** in `client/src/features/dashboard/Dashboard.jsx`
   - Fetches all data on every render
   - Should implement caching or pagination

### Medium Priority (8)
- TODO: Add input validation on frontend forms
- TODO: Implement websockets for real-time updates
- FIXME: Memory leak in dashboard component (useEffect cleanup)
- TODO: Add loading states for all async operations
- TODO: Implement proper error boundaries
- ...

### Low Priority (12)
- TODO: Update README with latest setup instructions
- TODO: Add TypeScript to frontend
- ...

---

## 🚀 Entry Points

### Development

Start frontend

cd client && npm run dev

Start backend

cd server && npm run dev

Start full stack

docker-compose up

### Testing

Backend tests

cd server && npm test

Frontend tests

cd client && npm test

### Production

Build frontend

cd client && npm run build

Start backend

cd server && npm start

---

## 📋 Common Tasks

### Adding a New Feature
1. Create feature folder in `client/src/features/{feature-name}/`
2. Add component, hooks, and API calls
3. Create backend endpoint in `server/src/api/{feature-name}.routes.js`
4. Implement service logic in `server/src/services/{feature-name}.service.js`
5. Add repository methods in `server/src/repositories/{feature-name}.repository.js`
6. Create database migration if needed
7. Write tests

### Database Changes
1. Create migration: `npm run migrate:create {migration-name}`
2. Update models in `server/src/models/`
3. Run migration: `npm run migrate:up`

### Deploying
1. Run tests: `npm test`
2. Build frontend: `cd client && npm run build`
3. Push to main branch
4. GitHub Actions will deploy automatically

---

## 🔗 Integration Points

### External Services
- PostgreSQL database (localhost:5432)
- No other external dependencies

### API Endpoints
- `POST /api/auth/login` - User authentication
- `POST /api/auth/register` - User registration
- `GET /api/tasks` - List all tasks
- `POST /api/tasks` - Create task
- `PUT /api/tasks/:id` - Update task
- `DELETE /api/tasks/:id` - Delete task
- `GET /api/dashboard` - Dashboard metrics

---

## 📚 Recommendations

### Immediate Actions
1. **Update outdated packages** (especially express for security patch)
2. **Add rate limiting** to auth endpoints (prevents brute force)
3. **Fix pagination** in task service (performance issue)
4. **Increase test coverage** to 80%+ (especially frontend)

### Short-term Improvements
1. **Add API documentation** (Swagger/OpenAPI)
2. **Implement refresh token rotation** (better security)
3. **Add TypeScript** to frontend (type safety)
4. **Refactor large dashboard component** (split into smaller components)

### Long-term Enhancements
1. **Add websockets** for real-time task updates
2. **Implement caching** (Redis) for frequently accessed data
3. **Add monitoring** (Sentry for errors, Analytics)
4. **Consider microservices** if app grows significantly

---

**Analysis complete!** This codebase is well-structured but needs attention to test coverage and security improvements. Start with updating packages and adding rate limiting.

Key Insights

• Quick identification: User learned the entire stack in 2 minutes
• Actionable: Clear list of what needs fixing immediately
• Prioritized: Technical debt sorted by urgency
• Practical: Common tasks documented for daily work

---

Example 2: Python Django Monolith

User Request

"I need to understand this legacy Django app before refactoring it."

Analysis Output

# LegacyERP - Repository Analysis

**Generated:** 2025-10-17 20:30:45
**Analyzed by:** Claude Code Repository Analyzer

---

## 📊 Overview

**Primary Language:** Python (92%), JavaScript (5%), HTML (3%)
**Framework:** Django 3.2 (LTS)
**Architecture:** MVC (Django's MVT pattern)
**Total Files:** 287 files
**Lines of Code:** 42,380 LOC
**Last Updated:** 6 months ago ⚠️

---

## 📁 Directory Structure

legacy-erp/ ├── apps/ # Django apps │ ├── accounts/ │ ├── inventory/ │ ├── sales/ │ ├── purchases/ │ └── reports/ ├── static/ # Static files ├── templates/ # HTML templates ├── media/ # User uploads └── manage.py

---

## 🛠 Technologies

- Django 3.2.20 (LTS, but 3.2.23 available - security updates)
- PostgreSQL 12
- Celery 5.2.7 (async tasks)
- Redis 4.5.5 (caching, Celery broker)
- jQuery 3.6.0 (frontend)

---

## ⚠️ Critical Findings

### Security Vulnerabilities
1. **Django 3.2.20 → 3.2.23** - 3 security patches available
2. **DEBUG = True** in production settings (exposes sensitive data)
3. **No rate limiting** on API endpoints
4. **SQL injection risk** in `apps/reports/views.py:145` (raw SQL query)

### Performance Issues
1. **N+1 queries** in 12 different views
2. **No database indexing** on frequently queried fields
3. **Large template files** (>1000 lines) slow to render

### Technical Debt
- **67 TODOs** across codebase
- **23 FIXMEs** (including 5 critical database issues)
- **8 HACK comments** indicating workarounds

---

## 🐛 Technical Debt (Top 10)

1. **CRITICAL** - SQL injection vulnerability in reports
2. **CRITICAL** - Passwords stored with weak hashing (SHA-1)
3. **HIGH** - No input validation on 15 forms
4. **HIGH** - Missing CSRF protection on AJAX endpoints
5. **HIGH** - Celery tasks have no retry logic
6. **MEDIUM** - Large models (>500 lines each)
7. **MEDIUM** - No API versioning
8. **MEDIUM** - Deprecated Django functions used
9. **LOW** - Missing docstrings on 80% of functions
10. **LOW** - Inconsistent code style

---

## 🚀 Refactoring Recommendations

### Phase 1: Security (Immediate)
1. Update Django to 3.2.23
2. Fix SQL injection vulnerability
3. Add rate limiting
4. Fix password hashing
5. Set DEBUG = False in production

### Phase 2: Performance (1-2 weeks)
1. Add `select_related()` and `prefetch_related()` to fix N+1 queries
2. Add database indexes
3. Implement caching for expensive queries
4. Split large templates into components

### Phase 3: Modernization (1-2 months)
1. Migrate to Django 4.2 (current LTS)
2. Add API (Django REST Framework)
3. Replace jQuery with modern frontend (React/Vue)
4. Add comprehensive testing
5. Implement CI/CD

---

**Next Steps:** Start with Phase 1 security fixes immediately. The SQL injection and password hashing issues are critical.

Key Insights

• Security-first: Immediately flagged critical vulnerabilities
• Actionable roadmap: Phased refactoring plan
• Risk assessment: Prioritized by severity
• Legacy understanding: Clear picture of technical debt

---

Example 3: Go Microservices

User Request

"Analyze our microservices architecture - I need to document the system."

Analysis Output

# PaymentPlatform - Repository Analysis

**Generated:** 2025-10-17 20:45:12
**Analyzed by:** Claude Code Repository Analyzer

---

## 📊 Overview

**Primary Language:** Go (95%), Dockerfile (3%), YAML (2%)
**Framework:** Microservices Architecture
**Architecture:** Domain-Driven Design per service
**Total Files:** 423 files across 8 services
**Lines of Code:** 67,200 LOC
**Last Updated:** 3 hours ago

---

## 📁 Directory Structure

payment-platform/ ├── services/ │ ├── auth-service/ # Authentication & authorization │ ├── user-service/ # User management │ ├── payment-service/ # Payment processing │ ├── billing-service/ # Billing & invoices │ ├── notification-service/ # Email/SMS notifications │ ├── analytics-service/ # Reporting & analytics │ ├── webhook-service/ # External webhooks │ └── admin-service/ # Admin dashboard API ├── api-gateway/ # Kong API Gateway config ├── shared/ # Shared libraries │ ├── proto/ # gRPC protobuf definitions │ ├── types/ # Common data structures │ └── utils/ # Shared utilities ├── infrastructure/ │ ├── kubernetes/ # K8s manifests │ ├── terraform/ # Infrastructure as code │ └── monitoring/ # Prometheus, Grafana └── docker-compose.yml # Local development

---

## 🏗 Architecture

**Pattern:** Microservices with DDD per service + API Gateway

### Services Communication

Client ↓ API Gateway (Kong) ↓ ┌─────────────────────────────────────┐ │ auth-service → user-service │ │ ↓ │ │ payment-service → billing-service│ │ ↓ │ │ notification-service │ └─────────────────────────────────────┘

### Technology per Service
- **Communication**: gRPC (internal), REST (external)
- **Databases**: PostgreSQL (6 services), MongoDB (analytics, notifications)
- **Message Queue**: RabbitMQ (events)
- **Caching**: Redis (all services)

---

## 🔍 Service Analysis

### auth-service
- **LOC:** 4,200
- **Dependencies:** JWT, bcrypt, Redis
- **Database:** PostgreSQL
- **API:** REST + gRPC
- **Health:** ✅ Good test coverage (82%)

### payment-service (⚠️ Needs attention)
- **LOC:** 12,800 (largest service - consider splitting)
- **Dependencies:** Stripe, PayPal, Braintree
- **Database:** PostgreSQL
- **API:** gRPC only
- **Health:** ⚠️ Low test coverage (45%)
- **Issues:**
  - 15 TODOs including webhook retry logic
  - No circuit breaker for external APIs
  - Missing idempotency keys

### notification-service
- **LOC:** 3,500
- **Dependencies:** SendGrid, Twilio
- **Database:** MongoDB
- **API:** gRPC + Event consumers
- **Health:** ✅ Good (78% test coverage)

(... analysis continues for all 8 services ...)

---

## 🐛 Technical Debt by Service

### High Priority Across Services
1. **payment-service**: Missing circuit breaker (risk of cascade failures)
2. **payment-service**: No idempotency (risk of duplicate charges)
3. **webhook-service**: No signature verification (security risk)
4. **All services**: Missing distributed tracing headers

### Medium Priority
1. **billing-service**: Inefficient PDF generation (slow)
2. **analytics-service**: No data retention policy
3. **admin-service**: Missing RBAC (role-based access control)

---

## 📊 Service Health Dashboard

| Service | LOC | Test Coverage | Complexity | Status |
|---------|-----|---------------|------------|--------|
| auth-service | 4.2K | 82% | Low | ✅ Healthy |
| user-service | 5.1K | 75% | Low | ✅ Healthy |
| payment-service | 12.8K | 45% | High | ⚠️ Needs work |
| billing-service | 6.3K | 68% | Medium | 🟡 OK |
| notification-service | 3.5K | 78% | Low | ✅ Healthy |
| analytics-service | 9.2K | 52% | Medium | 🟡 OK |
| webhook-service | 4.8K | 61% | Low | ⚠️ Security issue |
| admin-service | 7.1K | 70% | Low | ✅ Healthy |

---

## 🚀 Recommendations

### Immediate (This Week)
1. **Add circuit breaker** to payment-service (prevent cascade failures)
2. **Implement idempotency** in payment-service (prevent duplicate charges)
3. **Add webhook signature verification** (security)

### Short-term (This Month)
1. **Split payment-service** (too large - consider payment-processor-service)
2. **Add distributed tracing** (Jaeger/Zipkin) for better debugging
3. **Implement RBAC** in admin-service
4. **Increase test coverage** to 70%+ across all services

### Long-term (This Quarter)
1. **Add service mesh** (Istio/Linkerd) for better observability
2. **Implement event sourcing** for critical services
3. **Add chaos engineering** tests
4. **Consider CQRS** for analytics-service

---

**Architecture is solid overall, but payment-service needs immediate attention for reliability and security.**

Key Insights

• Service-by-service: Clear breakdown of each microservice
• Health dashboard: Visual representation of service status
• Architecture diagram: Shows communication flow
• Prioritized fixes: Immediate security and reliability issues flagged

See main SKILL.md for analysis workflow and patterns.md for pattern detection.

Architecture Pattern Library

Common software architecture patterns and how to detect them in codebases.

Pattern 1: MVC (Model-View-Controller)

###

Detection Signs

project/
├── models/          # Data structures
├── views/           # UI templates
├── controllers/     # Request handlers
└── routes/          # URL routing

Characteristics

• Separation of concerns: Data, presentation, logic separated
• Common in: Ruby on Rails, Django, Laravel, ASP.NET MVC
• Flow: User → Controller → Model → View → User

Example Structure (Rails)

app/
├── models/
│   ├── user.rb
│   └── post.rb
├── views/
│   ├── users/
│   └── posts/
├── controllers/
│   ├── users_controller.rb
│   └── posts_controller.rb

Analysis Notes

• Strengths: Clear separation, easy to understand
• Weaknesses: Can become bloated in large apps
• Refactoring suggestion: Consider service layer for complex business logic

---

Pattern 2: Layered Architecture

Detection Signs

project/
├── api/             # HTTP layer
├── services/        # Business logic
├── repositories/    # Data access
└── models/          # Data structures

Characteristics

• Horizontal layers: Each layer depends only on layer below
• Common in: Enterprise applications, microservices
• Flow: API → Service → Repository → Database

Example Structure (Node.js)

src/
├── api/
│   ├── routes/
│   └── controllers/
├── services/
│   ├── user.service.js
│   └── auth.service.js
├── repositories/
│   ├── user.repository.js
│   └── auth.repository.js
└── models/
    └── user.model.js

Analysis Notes

• Strengths: Testable, maintainable, scalable
• Weaknesses: Can be over-engineered for simple apps
• Refactoring suggestion: Add DTOs (Data Transfer Objects) between layers

---

Pattern 3: Feature-Based (Vertical Slices)

Detection Signs

project/
├── features/
│   ├── authentication/
│   │   ├── auth.controller.js
│   │   ├── auth.service.js
│   │   └── auth.test.js
│   ├── users/
│   │   ├── user.controller.js
│   │   ├── user.service.js
│   │   └── user.test.js

Characteristics

• Organized by feature: Each feature is self-contained
• Common in: Modern frontend apps, domain-driven design
• Flow: Feature folder contains everything for that feature

Example Structure (React)

src/
├── features/
│   ├── dashboard/
│   │   ├── Dashboard.jsx
│   │   ├── dashboard.hooks.js
│   │   ├── dashboard.api.js
│   │   └── dashboard.test.js
│   ├── profile/
│   │   ├── Profile.jsx
│   │   ├── profile.hooks.js
│   │   └── profile.test.js
└── shared/          # Shared utilities

Analysis Notes

• Strengths: High cohesion, easy to navigate, easy to delete features
• Weaknesses: Shared code can be tricky
• Refactoring suggestion: Create shared/ folder for cross-cutting concerns

---

Pattern 4: Domain-Driven Design (DDD)

Detection Signs

project/
├── domain/          # Business logic
├── application/     # Use cases
├── infrastructure/  # External concerns
└── interfaces/      # API/UI

Characteristics

• Domain-centric: Business logic is central
• Common in: Complex enterprise applications
• Flow: Interface → Application → Domain

Example Structure

src/
├── domain/
│   ├── user/
│   │   ├── user.entity.js
│   │   ├── user.repository.interface.js
│   │   └── user.service.js
│   └── order/
│       ├── order.entity.js
│       └── order.service.js
├── application/
│   ├── create-user.usecase.js
│   └── place-order.usecase.js
├── infrastructure/
│   ├── database/
│   └── email/
└── interfaces/
    ├── http/
    └── cli/

Analysis Notes

• Strengths: Models complex business domains accurately
• Weaknesses: High learning curve, can be overkill for simple apps
• Refactoring suggestion: Start simple, add DDD patterns as complexity grows

---

Pattern 5: Microservices

Detection Signs

project/
├── services/
│   ├── auth-service/
│   ├── user-service/
│   ├── payment-service/
│   └── notification-service/
├── api-gateway/
└── shared/

Characteristics

• Distributed: Each service is independent
• Common in: Large-scale applications, cloud-native apps
• Flow: API Gateway → Service A/B/C → Database A/B/C

Example Structure

monorepo/
├── services/
│   ├── auth/
│   │   ├── src/
│   │   ├── Dockerfile
│   │   └── package.json
│   ├── users/
│   │   ├── src/
│   │   ├── Dockerfile
│   │   └── package.json
├── api-gateway/
│   └── src/
├── shared/
│   └── types/
└── docker-compose.yml

Analysis Notes

• Strengths: Scalable, independent deployment, technology flexibility
• Weaknesses: Complexity, distributed system challenges, debugging harder
• Refactoring suggestion: Start with modular monolith, extract services as needed

---

Pattern 6: Monorepo

Detection Signs

project/
├── packages/
│   ├── frontend/
│   ├── backend/
│   └── shared/
├── package.json      # Workspace root
└── lerna.json or pnpm-workspace.yaml

Characteristics

• Single repository: Multiple packages/apps in one repo
• Common in: Organizations with multiple related projects
• Flow: Shared code lives in packages/shared

Example Structure (pnpm workspaces)

monorepo/
├── apps/
│   ├── web/
│   │   └── package.json
│   └── mobile/
│       └── package.json
├── packages/
│   ├── ui/
│   │   └── package.json
│   └── utils/
│       └── package.json
├── package.json
└── pnpm-workspace.yaml

Analysis Notes

• Strengths: Code sharing, atomic commits across projects, easier refactoring
• Weaknesses: Large repo size, CI/CD complexity
• Refactoring suggestion: Use build caching (Turborepo, Nx)

---

Pattern 7: Clean Architecture (Hexagonal/Ports & Adapters)

Detection Signs

project/
├── core/            # Business logic (no dependencies)
├── adapters/        # External integrations
│   ├── http/
│   ├── database/
│   └── messaging/
└── ports/           # Interfaces

Characteristics

• Dependency inversion: Core doesn't depend on external concerns
• Common in: Applications with complex external integrations
• Flow: Adapter → Port → Core

Example Structure

src/
├── core/
│   ├── domain/
│   │   └── user.entity.js
│   ├── usecases/
│   │   └── create-user.usecase.js
│   └── ports/
│       ├── user.repository.port.js
│       └── email.service.port.js
└── adapters/
    ├── http/
    │   └── user.controller.js
    ├── database/
    │   └── user.repository.postgres.js
    └── email/
        └── email.service.sendgrid.js

Analysis Notes

• Strengths: Highly testable, technology-agnostic core, easy to swap implementations
• Weaknesses: Many files and abstractions, can be over-engineered
• Refactoring suggestion: Use for apps with many external dependencies

---

Pattern 8: JAMstack

Detection Signs

project/
├── public/          # Static assets
├── src/
│   ├── pages/       # Pre-rendered pages
│   └── components/
├── api/             # Serverless functions
└── netlify.toml or vercel.json

Characteristics

• JavaScript + APIs + Markup: Pre-rendered static site + serverless functions
• Common in: Static sites, marketing sites, blogs
• Flow: Static HTML + Client-side JS → Serverless API

Example Structure (Next.js)

project/
├── pages/
│   ├── index.jsx
│   ├── about.jsx
│   └── api/
│       └── contact.js  # Serverless function
├── components/
├── public/
└── next.config.js

Analysis Notes

• Strengths: Fast, secure, scalable, cheap hosting
• Weaknesses: Limited real-time features, build times for large sites
• Refactoring suggestion: Use ISR (Incremental Static Regeneration) for frequently updated content

---

Pattern 9: Event-Driven Architecture

Detection Signs

project/
├── events/
│   ├── user.created.event.js
│   ├── order.placed.event.js
├── handlers/
│   ├── send-welcome-email.handler.js
│   ├── update-inventory.handler.js
└── infrastructure/
    └── event-bus/

Characteristics

• Asynchronous: Components communicate via events
• Common in: Real-time systems, distributed systems
• Flow: Event Producer → Event Bus → Event Consumers

Example Structure

src/
├── events/
│   ├── user-registered.event.js
│   └── payment-completed.event.js
├── publishers/
│   └── event.publisher.js
├── subscribers/
│   ├── email.subscriber.js
│   └── analytics.subscriber.js
└── infrastructure/
    └── rabbitmq/

Analysis Notes

• Strengths: Decoupled, scalable, resilient
• Weaknesses: Debugging harder, eventual consistency, message ordering
• Refactoring suggestion: Add event versioning and schema validation

---

Pattern 10: CQRS (Command Query Responsibility Segregation)

Detection Signs

project/
├── commands/        # Write operations
│   ├── create-user.command.js
│   └── update-profile.command.js
├── queries/         # Read operations
│   ├── get-user.query.js
│   └── list-users.query.js
├── write-model/     # Write database
└── read-model/      # Read database (denormalized)

Characteristics

• Separate read/write: Different models for queries vs commands
• Common in: High-performance systems, event-sourced systems
• Flow: Command → Write DB → Event → Read DB (projection)

Example Structure

src/
├── commands/
│   ├── handlers/
│   │   └── create-order.handler.js
│   └── validators/
├── queries/
│   ├── handlers/
│   │   └── get-order-details.handler.js
│   └── projections/
├── write-store/
│   └── postgres/
└── read-store/
    └── elasticsearch/

Analysis Notes

• Strengths: Optimized reads and writes independently, scalable
• Weaknesses: Complexity, eventual consistency, data duplication
• Refactoring suggestion: Use only when read/write patterns are very different

---

Detection Decision Tree

Has models/, views/, controllers/? → MVC
Has api/, services/, repositories/? → Layered Architecture
Has features/ with self-contained modules? → Feature-Based
Has domain/, application/, infrastructure/? → DDD
Has multiple services/ with Dockerfiles? → Microservices
Has packages/ or workspaces? → Monorepo
Has core/ and adapters/? → Clean Architecture
Has static pages/ and api/ serverless? → JAMstack
Has events/ and handlers/? → Event-Driven
Has separate commands/ and queries/? → CQRS

See main SKILL.md for analysis workflow and examples.md for real-world examples.