senior-architect

# Senior Architect Architecture design and analysis tools for making informed technical decisions. ## Table of Contents - [Quick Start](#quick-start) - [Tools Overview](#tools-overview) - [Architecture Diagram Generator](#1-architecture-diagram-generator) - [Dependency Analyzer](#2-dependency-analyzer) - [Project Architect](#3-project-architect) - [Decision Workflows](#decision-workflows) - [Database Selection](#database-selection-workflow) - [Architecture Pattern Selection](#architecture-pattern-selection-workflow) - [Monolith vs Microservices](#monolith-vs-microservices-decision) - [Reference Documentation](#reference-documentation) - [Tech Stack Coverage](#tech-stack-coverage) - [Common Commands](#common-commands) --- ## Quick Start ```bash # Generate architecture diagram from project python scripts/architecture_diagram_generator.py ./my-project --format mermaid # Analyze dependencies for issues python scripts/dependency_analyzer.py ./my-project --output json # Get architecture assessment 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:** ```bash # Mermaid format (default) python scripts/architecture_diagram_generator.py ./project --format mermaid --type component # PlantUML format python scripts/architecture_diagram_generator.py ./project --format plantuml --type layer # ASCII format (terminal-friendly) python scripts/architecture_diagram_generator.py ./project --format ascii # Save to file python scripts/architecture_diagram_generator.py ./project -o architecture.md ``` **Example output (Mermaid):** ```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:** ```bash # Human-readable report python scripts/dependency_analyzer.py ./project # JSON output for CI/CD integration python scripts/dependency_analyzer.py ./project --output json # Check only for circular dependencies python scripts/dependency_analyzer.py ./project --check circular # Verbose mode with recommendations 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:** ```bash # Full assessment python scripts/project_architect.py ./project # Verbose with detailed recommendations python scripts/project_architect.py ./project --verbose # JSON output python scripts/project_architect.py ./project --output json # Check specific aspect 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:** - [ ] Team is small (<10 developers) - [ ] Domain boundaries are unclear - [ ] Rapid iteration is priority - [ ] Operational complexity must be minimized - [ ] Shared database is acceptable **Choose Microservices when:** - [ ] Teams can own services end-to-end - [ ] Independent deployment is critical - [ ] Different scaling requirements per component - [ ] Technology diversity is needed - [ ] Domain boundaries are well understood **Hybrid approach:** Start with a modular monolith. Extract services only when: 1. A module has significantly different scaling needs 2. A team needs independent deployment 3. 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 ```bash # Architecture visualization python scripts/architecture_diagram_generator.py . --format mermaid python scripts/architecture_diagram_generator.py . --format plantuml python scripts/architecture_diagram_generator.py . --format ascii # Dependency analysis python scripts/dependency_analyzer.py . --verbose python scripts/dependency_analyzer.py . --check circular python scripts/dependency_analyzer.py . --output json # Architecture assessment python scripts/project_architect.py . --verbose python scripts/project_architect.py . --check layers python scripts/project_architect.py . --output json ``` --- ## Getting Help 1. Run any script with `--help` for usage information 2. Check reference documentation for detailed patterns and workflows 3. Use `--verbose` flag for detailed explanations and recommendations --- ## Why This Skill Exists Implement — This skill should be used when the user asks to <!-- SR_40: auto-generated from frontmatter `purpose`/`description` (OPP-Phase3). Expand with domain-specific rationale. --> ## When to Use Use this skill when the task requires senior architect capabilities. <!-- SR_40: auto-generated from frontmatter `when`/`description` (OPP-Phase3). --> ## What If Fails If this skill fails to produce the expected output: (1) verify input completeness, (2) retry with more specific context, (3) fall back to the parent workflow without this skill. <!-- SR_40: auto-generated from frontmatter `what_if_fails` (OPP-Phase3). -->