Professional software architecture skill for analyzing existing codebases,
designing new systems, creating comprehensive planning documents, and guiding
technical decision-making through structured architectural workflows.
Professional software architecture skill for analyzing existing codebases,
designing new systems, creating comprehensive planning documents, and guiding
technical decision-making through structured architectural workflows.
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?
-
-
### Integration
-
-
-
Step 1.2: Planning Document Generation
Create the following artifacts in project root:
1. DEVELOPMENT_PLAN.md
# 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]
## 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
4. TECH_STACK.md
# 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
5. SECURITY.md
# Security Architecture: [Project Name]## Authentication Strategy### Method: JWT Tokens- Access token lifetime: 15 minutes
- Refresh token lifetime: 7 days
- Tokens signed with RS256 (asymmetric)
### Implementation1. 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
Step 1.3: Handoff to Builder
---
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)
---
Phase 2: Existing Codebase Analysis
Evaluate and improve existing system architectures.
## Analysis Results### Current State- Score: 2.8/5 overall
- Critical Issues: No caching, single database, no CI/CD
### Recommendations1. 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
