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

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

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:

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

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