architect-role-skill

Professional software architecture skill for analyzing existing codebases, designing new systems, creating comprehensive planning documents, and guiding technical decision-making through structured architectural workflows.

Jump to install

Repository: enuno/claude-command-and-control
Last source activity: December 14, 2025 at 11:51
Detected SKILL.md language: English
Stars: 15
Forks: 3

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	architect-role-skill
version	1.0.0
category	architecture
complexity	high
status	active
created	2025-12-12T00:00:00.000Z
author	claude-command-and-control
description	Professional software architecture skill for analyzing existing codebases, designing new systems, creating comprehensive planning documents, and guiding technical decision-making through structured architectural workflows.
triggers	["design system","create architecture","analyze codebase","evaluate technology stack","architectural review"]
dependencies	[]
tags	["architecture","system-design","planning","technical-decisions","documentation"]

Architect Role Skill

Description

Analyze existing codebases for architectural improvements or guide greenfield projects through comprehensive software planning and system design. This skill implements professional architecture practices including requirements gathering, system design, technology selection, and comprehensive planning document generation.

When to Use This Skill

Designing new systems or applications (greenfield projects)
Analyzing existing codebases for architectural improvements
Evaluating and recommending technology stack changes
Creating comprehensive planning and architecture documents
Assessing scalability, maintainability, and performance
Documenting architectural decisions and trade-offs
Developing phased implementation roadmaps

When NOT to Use This Skill

For code implementation (use builder-role-skill)
For infrastructure deployment (use devops-role-skill)
For testing and validation (use validator-role-skill)
For documentation writing (use scribe-role-skill)

Prerequisites

Project requirements or existing codebase to analyze
Access to stakeholder requirements (for greenfield)
Git repository with project history (for analysis)
Understanding of target deployment environment

Workflow

Phase 1: Greenfield Project Initialization

Design new systems from requirements through comprehensive planning.

Step 1.1: Requirements Discovery

Engage stakeholders with structured questions:

## Requirements Discovery Questionnaire

### Business Goals
- What problem does this application solve?
- Who are the target users?
- What are the critical features?
- What are the success metrics?

### Technical Requirements
- What are the performance requirements?
- What are the scalability expectations?
- What are the security requirements?
- What compliance standards must be met?

### Constraints
- What are the budget constraints?
- What are the timeline constraints?
 What technologies are you familiar with?
 What deployment environment (cloud, on-premise, hybrid)?


 What existing systems must integrate with this?
 What third-party services are required?
 What data sources need to be connected?

# Development Plan: [Project Name]

## Executive Summary
[1-2 paragraph overview of the project, its goals, and approach]

## System Architecture Overview
[High-level description of system components and their relationships]

## Technology Stack Justification

### Frontend
- Framework: [Choice]
- Rationale: [Why this was selected]
- Alternatives Considered: [What was rejected and why]

### Backend
- Framework: [Choice]
- Rationale: [Why this was selected]
- Alternatives Considered: [What was rejected and why]

### Database
- System: [Choice]
- Rationale: [Why this was selected]
- Schema Strategy: [Relational/Document/Graph]

### Infrastructure
- Hosting: [Cloud provider/On-premise]
- Container Orchestration: [If applicable]
- CI/CD: [Tools selected]

## Component Breakdown

### Component 1: [Name]
- Purpose: [What it does]
- Responsibilities: [Key functions]
- Dependencies: [What it depends on]
- API Surface: [Public interfaces]

### Component 2: [Name]
[Same structure...]

## Data Model Design

### Entity: [Name]


## API Specifications

### Endpoint: [Method] [Path]
- Purpose: [What it does]
- Request: [Schema]
- Response: [Schema]
- Authentication: [Requirements]
- Rate Limiting: [Policy]

## Security Architecture
- Authentication Strategy: [JWT/Session/OAuth/etc]
- Authorization Model: [RBAC/ABAC/etc]
- Data Encryption: [At rest/In transit]
- Secrets Management: [Vault/KMS/etc]
- Security Testing: [SAST/DAST/Penetration testing]

## Deployment Strategy
- Environments: [Dev/Staging/Production]
- Deployment Method: [Blue-green/Canary/Rolling]
- Rollback Strategy: [How to recover from failures]
- Monitoring: [What to monitor]
- Alerting: [When to alert]

## Development Phases

### Phase 1: Foundation (Weeks 1-2)
- [ ] Database schema implementation
- [ ] Authentication service
- [ ] Basic API structure
- [ ] Development environment setup

### Phase 2: Core Features (Weeks 3-5)
- [ ] Feature 1 implementation
- [ ] Feature 2 implementation
- [ ] Integration testing

### Phase 3: Integration & Polish (Weeks 6-8)
- [ ] Third-party integrations
- [ ] Performance optimization
- [ ] Security hardening
- [ ] Documentation

### Phase 4: Launch (Week 9)
- [ ] Production deployment
- [ ] Monitoring setup
- [ ] Post-launch support plan

## Success Metrics
- Performance: [Specific targets]
- Reliability: [Uptime targets]
- User Adoption: [Metrics]
- Business Impact: [KPIs]

# Project Tasks: [Project Name]

## Phase 1: Foundation

### High Priority
- [ ] Task 1: [Description] (Estimated: 8h, Complexity: Medium)
- [ ] Task 2: [Description] (Estimated: 12h, Complexity: High)

### Medium Priority
- [ ] Task 3: [Description] (Estimated: 4h, Complexity: Low)

### Low Priority
- [ ] Task 4: [Description] (Estimated: 6h, Complexity: Medium)

## Dependencies
- Task 2 depends on Task 1
- Task 3 can run in parallel with Task 1

## Assignment Recommendations
- Task 1: Builder Agent (database expertise)
- Task 2: Builder Agent (API development)

# Architecture: [Project Name]

## System Overview


## Component Interactions

### Client → API Gateway
- Protocol: HTTPS/REST
- Authentication: JWT tokens
- Rate Limiting: 100 req/min per user

### API Gateway → Services
- Protocol: gRPC / REST
- Service Discovery: [Method]
- Load Balancing: [Strategy]

## Data Flow Patterns

### Write Path
1. Client sends request to API Gateway
2. Gateway validates JWT token
3. Request routed to appropriate service
4. Service validates business rules
5. Service writes to database
6. Async notification sent if needed
7. Response returned to client

### Read Path
1. Client requests data
2. Check cache (Redis)
3. If miss, query database
4. Transform and return data
5. Update cache for future requests

## Scalability Considerations

### Horizontal Scaling
- Stateless services behind load balancer
- Database read replicas for read-heavy workloads
- Cache layer (Redis/Memcached) to reduce DB load

### Vertical Scaling
- Database can scale up to handle write load
- Background workers for async processing

### Bottlenecks
- Primary database writes (mitigated by caching)
- Third-party API rate limits (mitigated by queuing)

## Failure Modes and Resilience

### Database Failure
- Impact: Service degradation
- Mitigation: Read replicas, automatic failover
- Recovery Time: < 5 minutes

### Service Failure
- Impact: Partial functionality loss
- Mitigation: Circuit breakers, graceful degradation
- Recovery Time: Automatic restart

### Third-Party API Failure
- Impact: Feature unavailable
- Mitigation: Queue requests, retry with backoff
- Recovery Time: When API recovers

# Technology Stack: [Project Name]

## Frontend

### Framework: React
**Rationale**:
- Large ecosystem and community support
- Component-based architecture aligns with our design
- Strong TypeScript support for type safety
- Team has existing expertise

**Alternatives Considered**:
- Vue.js: Simpler but smaller ecosystem
- Angular: Too heavyweight for our needs
- Svelte: Less mature ecosystem

### State Management: Redux Toolkit
**Rationale**:
- Predictable state updates
- Time-travel debugging
- Middleware for async operations

## Backend

### Framework: Node.js + Express
**Rationale**:
- JavaScript across stack reduces context switching
- Excellent async I/O performance
- Rich ecosystem of packages
- Fast development cycle

**Alternatives Considered**:
- Python/Django: Slower for I/O-heavy operations
- Java/Spring: More verbose, longer build times
- Go: Team unfamiliar, learning curve

### Database: PostgreSQL
**Rationale**:
- ACID compliance for data integrity
- Rich querying capabilities (JSON, full-text search)
- Proven scalability
- Open source with strong community

**Schema Design**:
- Relational model for core entities
- JSONB columns for flexible metadata
- Indexes on frequently queried fields

## Infrastructure

### Hosting: AWS
**Services Used**:
- EC2: Application servers
- RDS: Managed PostgreSQL
- S3: Static assets and backups
- CloudFront: CDN for global distribution
- Lambda: Serverless background tasks

**Rationale**:
- Mature ecosystem with comprehensive services
- Auto-scaling capabilities
- Global infrastructure
- Team familiarity

### Container Orchestration: Kubernetes
**Rationale**:
- Declarative configuration
- Automatic scaling and healing
- Platform-agnostic (can migrate from AWS)

### CI/CD: GitHub Actions
**Rationale**:
- Integrated with repository
- Free for public repos, affordable for private
- YAML configuration versioned with code

## Third-Party Services

### Authentication: Auth0
**Rationale**:
- Proven security
- Multiple auth providers (OAuth, SAML)
- Reduces development effort

### Monitoring: Datadog
**Rationale**:
- Comprehensive metrics and logs
- Alerting capabilities
- APM for performance monitoring

### Error Tracking: Sentry
**Rationale**:
- Real-time error notifications
- Source map support
- Issue tracking integration

# Security Architecture: [Project Name]

## Authentication Strategy

### Method: JWT Tokens
- Access token lifetime: 15 minutes
- Refresh token lifetime: 7 days
- Tokens signed with RS256 (asymmetric)

### Implementation
1. User authenticates with credentials
2. Server issues access + refresh token
3. Client stores tokens securely (httpOnly cookies)
4. Access token used for API requests
5. Refresh token used to obtain new access token

## Authorization Model

### Role-Based Access Control (RBAC)
**Roles**:
- Admin: Full system access
- Manager: Department-level access
- User: Personal data access only
- Guest: Read-only public data

**Permission Checking**:
- Middleware validates JWT and extracts role
- Route handlers check required permissions
- Database queries filtered by user context

## Data Encryption

### At Rest
- Database: AWS RDS encryption with KMS
- Backups: S3 server-side encryption
- PII fields: Application-level encryption (AES-256)

### In Transit
- All API traffic over HTTPS (TLS 1.3)
- Internal services use mutual TLS
- Database connections encrypted

## Secrets Management
- Environment variables for non-sensitive config
- AWS Secrets Manager for sensitive credentials
- Rotation policy: Every 90 days
- Access audited and logged

## Compliance Requirements

### GDPR
- User data export capability
- Right to deletion implementation
- Consent tracking
- Data processing agreements with third parties

### Security Testing Plan
- Automated SAST scans on every PR
- Dependency vulnerability scanning (Dependabot)
- Penetration testing: Quarterly
- Security audit: Annually

---
TO: Builder (or use builder-role-skill)
PHASE: Phase 1 - Foundation
PRIORITY: High
SCOPE: Database schema and authentication service
REFERENCE_DOCS:
  - DEVELOPMENT_PLAN.md (Section: Component Breakdown)
  - ARCHITECTURE.md (Section: Data Model Design)
  - SECURITY.md (Section: Authentication Strategy)
ACCEPTANCE_CRITERIA:
  - Database schema implements all entities
  - Authentication endpoints functional
  - JWT token generation/validation working
  - Unit tests coverage >= 90%
DEPENDENCIES: None (starting point)
---

# Examine project structure
find . -type f \( -name "*.js" -o -name "*.py" -o -name "*.java" \) | head -50

# Review dependencies
cat package.json 2>/dev/null || cat requirements.txt 2>/dev/null || cat pom.xml 2>/dev/null

# Analyze git activity
git log --oneline --since="6 months ago" --pretty=format:"%h %s" | head -20

# Identify most changed files (potential hotspots)
git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rg | head -20

Dimension	Score	Notes
Code Organization		Modularity, separation of concerns
Documentation		README, API docs, inline comments
Testing		Coverage, test quality, CI integration
Security		Auth, data protection, vulnerability scan
Performance		Response times, resource usage, optimization
Scalability		Horizontal/vertical scaling capability
Maintainability		Code complexity, technical debt
Modern Practices		Version control, CI/CD, code review

# Architecture Review: [Project Name]

## Executive Summary
[1-2 paragraphs summarizing current state and key recommendations]

## Current State Assessment

### Strengths
1. **[Aspect]**: [What's working well and why]
2. **[Aspect]**: [What's working well and why]

### Critical Issues
1. **[Issue]**:
   - Impact: [Business/Technical impact]
   - Risk: [High/Medium/Low]
   - Recommendation: [What to do]

### Architecture Scores

| Dimension | Score | Status | Priority |
|-----------|-------|--------|----------|
| Code Organization | 3/5 | ⚠️ Needs Improvement | High |
| Documentation | 2/5 | ❌ Critical | High |
| Testing | 4/5 | ✅ Good | Medium |
| Security | 3/5 | ⚠️ Needs Improvement | High |
| Performance | 4/5 | ✅ Good | Low |
| Scalability | 2/5 | ❌ Critical | High |
| Maintainability | 3/5 | ⚠️ Needs Improvement | Medium |
| Modern Practices | 4/5 | ✅ Good | Low |

## Recommended Improvements (Prioritized)

### Priority 1: Critical (Must Address)
1. **Improve Scalability**
   - Current Issue: Single database instance, no caching
   - Recommendation: Implement read replicas + Redis caching layer
   - Effort: 2-3 weeks
   - Benefit: Handle 10x traffic without degradation

2. **Address Documentation Gaps**
   - Current Issue: No API documentation, minimal inline comments
   - Recommendation: Generate OpenAPI specs, add JSDoc comments
   - Effort: 1 week
   - Benefit: Onboarding time reduced by 50%

### Priority 2: Important (Should Address)
1. **Refactor Monolithic Service**
   - Current Issue: Single service handles all business logic
   - Recommendation: Extract payment processing to separate service
   - Effort: 3-4 weeks
   - Benefit: Independent scaling, clearer boundaries

### Priority 3: Nice to Have
1. **Modernize Frontend Build**
   - Current Issue: Using Webpack 4
   - Recommendation: Migrate to Vite for faster builds
   - Effort: 1 week
   - Benefit: Development build time from 45s to 5s

## Migration/Refactoring Strategy

### Phase 1: Foundation (Month 1)
- Implement caching layer
- Add comprehensive logging
- Create API documentation

### Phase 2: Scaling Improvements (Month 2)
- Set up database read replicas
- Implement connection pooling
- Add load balancer

### Phase 3: Service Extraction (Month 3-4)
- Extract payment service
- Implement service mesh
- Update deployment pipeline

## Risk Mitigation

### Risk: Database Migration Downtime
- Mitigation: Use blue-green deployment with gradual traffic shift
- Fallback: Immediate rollback capability

### Risk: Breaking Changes During Refactoring
- Mitigation: Comprehensive test suite before starting
- Fallback: Feature flags to disable new code paths

## Estimated Effort and Timeline

| Phase | Duration | Team Size | Risk Level |
|-------|----------|-----------|------------|
| Phase 1 | 1 month | 2 engineers | Low |
| Phase 2 | 1 month | 2 engineers | Medium |
| Phase 3 | 2 months | 3 engineers | High |

**Total**: 4 months with 2-3 engineers

---
TO: Builder (or use builder-role-skill)
TASK: Implement Redis caching layer
REFERENCE: ARCHITECTURE_REVIEW.md (Priority 1, Item 1)
ESTIMATED_EFFORT: 2 weeks
---

---
TO: Validator (or use validator-role-skill)
TASK: Security audit of authentication flow
REFERENCE: ARCHITECTURE_REVIEW.md (Security Score: 3/5)
---

---
TO: Scribe (or use scribe-role-skill)
TASK: Generate OpenAPI documentation
REFERENCE: ARCHITECTURE_REVIEW.md (Priority 1, Item 2)
---

Handoff Message Format:
---
TO: Builder
PHASE: [Phase name]
PRIORITY: [High/Medium/Low]
SCOPE: [Brief description]
REFERENCE_DOCS:
  - DEVELOPMENT_PLAN.md (Section X)
  - ARCHITECTURE.md (Component Y)
ACCEPTANCE_CRITERIA:
  - [Specific, measurable criteria]
DEPENDENCIES: [Prerequisites]
---

## Key Decisions

### Technology Stack
- Frontend: React (team expertise)
- Backend: Node.js + Express (async I/O for concurrent users)
- Database: PostgreSQL (ACID for orders)
- Cache: Redis (session + product catalog)

### Architecture Pattern
- Microservices for:
  - User service
  - Product catalog service
  - Order processing service
  - Payment service

### Scalability Strategy
- Horizontal scaling behind load balancer
- Database read replicas for product searches
- CDN for static assets

**Result**: 5 comprehensive planning documents created, ready for builder implementation

## Analysis Results

### Current State
- Score: 2.8/5 overall
- Critical Issues: No caching, single database, no CI/CD

### Recommendations
1. Add Redis caching (2 weeks, high priority)
2. Set up CI/CD pipeline (1 week, high priority)
3. Extract payment module to service (4 weeks, medium priority)

### Migration Strategy
- Strangler Fig pattern over 6 months
- Zero-downtime migration approach

**Result**: Prioritized roadmap with risk mitigation, ready for phased execution