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:

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

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

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