Senior Architect
Architecture design and analysis tools for making informed technical decisions.
Table of Contents
- Quick Start
- Tools Overview
- Decision Workflows
- Reference Documentation
- Tech Stack Coverage
- 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 relationshipslayer- 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):
mermaidgraph 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:
- 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
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
- Run any script with
--helpfor usage information - Check reference documentation for detailed patterns and workflows
- Use
--verboseflag for detailed explanations and recommendations
