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

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

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

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:

references/architecture_patterns.md

references/system_design_workflows.md

references/tech_decision_guide.md

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

Troubleshooting

node_modules

.venv

dependency_analyzer.py --verbose

src/

services/

controllers/

--format plantuml

package.json

requirements.txt

go.mod

Cargo.toml

npm ls

pip check

go mod verify

references/architecture_patterns.md

Success Criteria

• Coupling score below 30: The dependency analyzer reports a coupling score under 30/100, indicating loosely coupled modules with clear boundaries.
• Zero circular dependencies: Running

  dependency_analyzer.py --check circular

  exits with code 0 and reports no cycles.
• Zero layer violations: Running

  project_architect.py --check layers

  detects no cross-layer dependency violations.
• Architecture pattern confidence above 70%: The project architect detects a recognized pattern (layered, clean, hexagonal, MVC) with at least 70% confidence.
• No god classes detected: Every class in the codebase stays below 300 lines, with no

  god_class

  issues in the assessment report.
• Average file size under 250 lines: The code quality metrics show

  avg_file_lines

  well below the 500-line threshold, indicating well-decomposed modules.
• ADR created for every major decision: Each architecture decision is documented using the ADR template from the database selection or pattern selection workflow.

Scope & Limitations

What this skill covers:

• System-level architecture analysis: pattern detection, layer validation, and component diagramming for existing codebases.
• Technology-agnostic dependency analysis across npm, pip, Poetry, Go modules, and Cargo.
• Architecture decision workflows for database selection, pattern selection, and monolith-vs-microservices trade-offs.
• Diagram generation in Mermaid, PlantUML, and ASCII formats for documentation and team review.

What this skill does NOT cover:

• Runtime performance profiling or load testing -- use

  senior-devops

  for infrastructure capacity planning and

  senior-qa

  for performance test harnesses.
• Security vulnerability scanning of dependencies -- use

  senior-security

  or

  senior-secops

  for CVE detection and SAST/DAST analysis.
• Frontend component architecture and design system auditing -- use

  senior-frontend

  for React/Vue/Angular component patterns and

  design-auditor

  for UI consistency checks.
• CI/CD pipeline design and deployment orchestration -- use

  senior-devops

  for pipeline configuration and

  release-orchestrator

  for release workflows.

Integration Points

senior-backend

senior-devops

senior-security

--output json

senior-fullstack

project_scaffolder.py --type

code-reviewer

project_architect.py --output json

tech-stack-evaluator

Tool Reference

architecture_diagram_generator.py

• Purpose: Generates architecture diagrams from project directory structure in Mermaid, PlantUML, or ASCII format.
• Usage:

  python scripts/architecture_diagram_generator.py <project_path> [flags]

• Flags:

project_path

--format

-f

mermaid

plantuml

ascii

mermaid

--type

-t

component

layer

deployment

component

--output

-o

--verbose

-v

--json

• Example:

python scripts/architecture_diagram_generator.py ./my-app --format mermaid --type layer -v

Scanning project: /home/user/my-app
Found 6 components
Found 4 relationships
Technologies: node, react, docker
graph TB
    subgraph Presentation Layer
        components["components"]
        pages["pages"]
    end

    subgraph Business Layer
        services["services"]
    end

    subgraph Data Layer
        models["models"]
        repositories["repositories"]
    end

• Output Formats: Mermaid diagram code (copy into any Mermaid renderer), PlantUML markup (render via PlantUML server), ASCII art (paste into terminal or plain-text docs), or raw JSON scan data (

  --json

  ).

dependency_analyzer.py

• Purpose: Analyzes project dependencies for coupling score, circular dependencies, and package health across multiple package managers.
• Usage:

  python scripts/dependency_analyzer.py <project_path> [flags]

• Flags:

project_path

--output

-o

human

json

human

--check

all

circular

coupling

all

circular

coupling

--verbose

-v

--save

-s

• Example:

python scripts/dependency_analyzer.py ./my-app --output json --save report.json

{
  "project_path": "/home/user/my-app",
  "package_manager": "npm",
  "summary": {
    "direct_dependencies": 23,
    "dev_dependencies": 15,
    "internal_modules": 8,
    "coupling_score": 42,
    "circular_dependencies": 1,
    "issues": 1
  },
  "circular_dependencies": [["auth", "user", "permissions", "auth"]],
  "recommendations": [
    "Extract shared interfaces or create a common module to break circular dependencies"
  ]
}

• Output Formats: Human-readable terminal report (default) with summary, issues, and recommendations; JSON structured report for CI/CD pipeline integration or programmatic consumption.

project_architect.py

• Purpose: Detects architectural patterns, code organization issues, layer violations, and god classes in a project, then generates improvement recommendations.
• Usage:

  python scripts/project_architect.py <project_path> [flags]

• Flags:

project_path

--output

-o

human

json

human

--check

all

pattern

layers

code

all

pattern

layers

code

--verbose

-v

--save

-s

• Example:

python scripts/project_architect.py ./my-app --check layers --verbose

Analyzing project: /home/user/my-app
Detected pattern: layered (confidence: 78%)
Found 2 code issues
Found 1 layer violations
Found 1 layer violation(s):
  controllers/PaymentController.ts: presentation layer should not depend on infrastructure layer

• Output Formats: Human-readable terminal report (default) with pattern detection, layer assignments, code issues, and prioritized recommendations; JSON structured report for automated quality gates and dashboard integration.