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 projectpython scripts/architecture_diagram_generator.py ./my-project --format mermaid
# Analyze dependencies for issuespython scripts/dependency_analyzer.py ./my-project --output json
# Get architecture assessmentpython 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:

# Mermaid format (default)python scripts/architecture_diagram_generator.py ./project --format mermaid --type component
# PlantUML formatpython 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 filepython 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 reportpython scripts/dependency_analyzer.py ./project
# JSON output for CI/CD integrationpython scripts/dependency_analyzer.py ./project --output json
# Check only for circular dependenciespython scripts/dependency_analyzer.py ./project --check circular
# Verbose mode with recommendationspython 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 dependency2. 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 assessmentpython scripts/project_architect.py ./project
# Verbose with detailed recommendationspython scripts/project_architect.py ./project --verbose
# JSON outputpython scripts/project_architect.py ./project --output json
# Check specific aspectpython 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 services2. Move business logic from controllers to services3. 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

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 applicationsMongoDB    → Document store, flexible schemaRedis      → Caching, sessions, real-time featuresDynamoDB   → Serverless, auto-scaling, AWS-nativeTimescaleDB → 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

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 visualizationpython scripts/architecture_diagram_generator.py . --format mermaidpython scripts/architecture_diagram_generator.py . --format plantumlpython scripts/architecture_diagram_generator.py . --format ascii
# Dependency analysispython scripts/dependency_analyzer.py . --verbosepython scripts/dependency_analyzer.py . --check circularpython scripts/dependency_analyzer.py . --output json
# Architecture assessmentpython scripts/project_architect.py . --verbosepython scripts/project_architect.py . --check layerspython 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