| name | senior-architect |
| description | This skill should be used when the user asks to "design system architecture", "evaluate microservices vs monolith", "create architecture diagrams", "analyze dependencies", "choose a database", "plan for scalability", "make technical decisions", or "review system design". Use for architecture decision records (ADRs), tech stack evaluation, system design reviews, dependency analysis, and generating architecture diagrams in Mermaid, PlantUML, or ASCII format. |
Senior Architect
Architecture design and analysis tools for making informed technical decisions.
Table of Contents
Quick Start
python scripts/architecture_diagram_generator.py ./my-project --format mermaid
python scripts/dependency_analyzer.py ./my-project --output json
python scripts/project_architect.py ./my-project --verbose
Tools Overview
1. Architecture Diagram Generator
Generates architecture diagrams from project structure in multiple formats.
Solves: "I need to visualize my system architecture for documentation or team discussion"
Input: Project directory path
Output: Diagram code (Mermaid, PlantUML, or ASCII)
Supported diagram types:
component - Shows modules and their relationships
layer - Shows architectural layers (presentation, business, data)
deployment - Shows deployment topology
Usage:
python scripts/architecture_diagram_generator.py ./project --format mermaid --type component
python scripts/architecture_diagram_generator.py ./project --format plantuml --type layer
python scripts/architecture_diagram_generator.py ./project --format ascii
python scripts/architecture_diagram_generator.py ./project -o architecture.md
Example output (Mermaid):
graph TD
A[API Gateway] --> B[Auth Service]
A --> C[User Service]
B --> D[(PostgreSQL)]
C --> D
2. Dependency Analyzer
Analyzes project dependencies for coupling, circular dependencies, and outdated packages.
Solves: "I need to understand my dependency tree and identify potential issues"
Input: Project directory path
Output: Analysis report (JSON or human-readable)
Analyzes:
- Dependency tree (direct and transitive)
- Circular dependencies between modules
- Coupling score (0-100)
- Outdated packages
Supported package managers:
- npm/yarn (
package.json)
- Python (
requirements.txt, pyproject.toml)
- Go (
go.mod)
- Rust (
Cargo.toml)
Usage:
python scripts/dependency_analyzer.py ./project
python scripts/dependency_analyzer.py ./project --output json
python scripts/dependency_analyzer.py ./project --check circular
python scripts/dependency_analyzer.py ./project --verbose
Example output:
Dependency Analysis Report
==========================
Total dependencies: 47 (32 direct, 15 transitive)
Coupling score: 72/100 (moderate)
Issues found:
- CIRCULAR: auth → user → permissions → auth
- OUTDATED: lodash 4.17.15 → 4.17.21 (security)
Recommendations:
1. Extract shared interface to break circular dependency
2. Update lodash to fix CVE-2020-8203
3. Project Architect
Analyzes project structure and detects architectural patterns, code smells, and improvement opportunities.
Solves: "I want to understand the current architecture and identify areas for improvement"
Input: Project directory path
Output: Architecture assessment report
Detects:
- Architectural patterns (MVC, layered, hexagonal, microservices indicators)
- Code organization issues (god classes, mixed concerns)
- Layer violations
- Missing architectural components
Usage:
python scripts/project_architect.py ./project
python scripts/project_architect.py ./project --verbose
python scripts/project_architect.py ./project --output json
python scripts/project_architect.py ./project --check layers
Example output:
Architecture Assessment
=======================
Detected pattern: Layered Architecture (confidence: 85%)
Structure analysis:
✓ controllers/ - Presentation layer detected
✓ services/ - Business logic layer detected
✓ repositories/ - Data access layer detected
⚠ models/ - Mixed domain and DTOs
Issues:
- LARGE FILE: UserService.ts (1,847 lines) - consider splitting
- MIXED CONCERNS: PaymentController contains business logic
Recommendations:
1. Split UserService into focused services
2. Move business logic from controllers to services
3. Separate domain models from DTOs
Decision Workflows
Database Selection Workflow
Use when choosing a database for a new project or migrating existing data.
Step 1: Identify data characteristics
| Characteristic | Points to SQL | Points to NoSQL |
|---|
| Structured with relationships | ✓ | |
| ACID transactions required | ✓ | |
| Flexible/evolving schema | | ✓ |
| Document-oriented data | | ✓ |
| Time-series data | | ✓ (specialized) |
Step 2: Evaluate scale requirements
- <1M records, single region → PostgreSQL or MySQL
- 1M-100M records, read-heavy → PostgreSQL with read replicas
-
100M records, global distribution → CockroachDB, Spanner, or DynamoDB
- High write throughput (>10K/sec) → Cassandra or ScyllaDB
Step 3: Check consistency requirements
- Strong consistency required → SQL or CockroachDB
- Eventual consistency acceptable → DynamoDB, Cassandra, MongoDB
Step 4: Document decision
Create an ADR (Architecture Decision Record) with:
- Context and requirements
- Options considered
- Decision and rationale
- Trade-offs accepted
Quick reference:
PostgreSQL → Default choice for most applications
MongoDB → Document store, flexible schema
Redis → Caching, sessions, real-time features
DynamoDB → Serverless, auto-scaling, AWS-native
TimescaleDB → Time-series data with SQL interface
Architecture Pattern Selection Workflow
Use when designing a new system or refactoring existing architecture.
Step 1: Assess team and project size
| Team Size | Recommended Starting Point |
|---|
| 1-3 developers | Modular monolith |
| 4-10 developers | Modular monolith or service-oriented |
| 10+ developers | Consider microservices |
Step 2: Evaluate deployment requirements
- Single deployment unit acceptable → Monolith
- Independent scaling needed → Microservices
- Mixed (some services scale differently) → Hybrid
Step 3: Consider data boundaries
- Shared database acceptable → Monolith or modular monolith
- Strict data isolation required → Microservices with separate DBs
- Event-driven communication fits → Event-sourcing/CQRS
Step 4: Match pattern to requirements
| Requirement | Recommended Pattern |
|---|
| Rapid MVP development | Modular Monolith |
| Independent team deployment | Microservices |
| Complex domain logic | Domain-Driven Design |
| High read/write ratio difference | CQRS |
| Audit trail required | Event Sourcing |
| Third-party integrations | Hexagonal/Ports & Adapters |
See references/architecture_patterns.md for detailed pattern descriptions.
Monolith vs Microservices Decision
Choose Monolith when:
Choose Microservices when:
Hybrid approach:
Start with a modular monolith. Extract services only when:
- A module has significantly different scaling needs
- A team needs independent deployment
- Technology constraints require separation
Reference Documentation
Load these files for detailed information:
| File | Contains | Load when user asks about |
|---|
references/architecture_patterns.md | 9 architecture patterns with trade-offs, code examples, and when to use | "which pattern?", "microservices vs monolith", "event-driven", "CQRS" |
references/system_design_workflows.md | 6 step-by-step workflows for system design tasks | "how to design?", "capacity planning", "API design", "migration" |
references/tech_decision_guide.md | Decision matrices for technology choices | "which database?", "which framework?", "which cloud?", "which cache?" |
Tech Stack Coverage
Languages: TypeScript, JavaScript, Python, Go, Swift, Kotlin, Rust
Frontend: React, Next.js, Vue, Angular, React Native, Flutter
Backend: Node.js, Express, FastAPI, Go, GraphQL, REST
Databases: PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, Cassandra
Infrastructure: Docker, Kubernetes, Terraform, AWS, GCP, Azure
CI/CD: GitHub Actions, GitLab CI, CircleCI, Jenkins
Common Commands
python scripts/architecture_diagram_generator.py . --format mermaid
python scripts/architecture_diagram_generator.py . --format plantuml
python scripts/architecture_diagram_generator.py . --format ascii
python scripts/dependency_analyzer.py . --verbose
python scripts/dependency_analyzer.py . --check circular
python scripts/dependency_analyzer.py . --output json
python scripts/project_architect.py . --verbose
python scripts/project_architect.py . --check layers
python scripts/project_architect.py . --output json
Getting Help
- Run any script with
--help for usage information
- Check reference documentation for detailed patterns and workflows
- Use
--verbose flag for detailed explanations and recommendations