Senior Architect

Senior Architect

Architecture design and analysis tools for making informed technical decisions.

Table of Contents

Quick Start Tools Overview Architecture Diagram Generator Dependency Analyzer Project Architect Decision Workflows Database Selection Architecture Pattern Selection Monolith vs Microservices Reference Documentation Tech Stack Coverage Common Commands

Quick Start

# 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

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: # 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): 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:
• # 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:
• # 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

Database Selection Workflow

Use when choosing a database for a new project or migrating existing data. Step 1: Identify data characteristics CharacteristicPoints to SQLPoints to NoSQLStructured 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 SizeRecommended Starting Point1-3 developersModular monolith4-10 developersModular monolith or service-oriented10+ developersConsider 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 RequirementRecommended PatternRapid MVP developmentModular MonolithIndependent team deploymentMicroservicesComplex domain logicDomain-Driven DesignHigh read/write ratio differenceCQRSAudit trail requiredEvent SourcingThird-party integrationsHexagonal/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: A module has significantly different scaling needs A team needs independent deployment Technology constraints require separation

Reference Documentation

Load these files for detailed information: FileContainsLoad when user asks aboutreferences/architecture_patterns.md9 architecture patterns with trade-offs, code examples, and when to use"which pattern?", "microservices vs monolith", "event-driven", "CQRS"references/system_design_workflows.md6 step-by-step workflows for system design tasks"how to design?", "capacity planning", "API design", "migration"references/tech_decision_guide.mdDecision 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

# 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

Run any script with --help for usage information Check reference documentation for detailed patterns and workflows Use --verbose flag for detailed explanations and recommendations