Senior Architect

Architecture design and analysis tools for making informed technical decisions.

Quick Start
Tools Overview
Decision Workflows
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

Troubleshooting

Problem	Cause	Solution
Diagram shows zero components	Project uses non-standard directory structure or all directories are in the ignore list (e.g., `node_modules`, `.venv`)	Ensure source code lives in named subdirectories at the project root, not solely in ignored folders
Circular dependency detection misses cycles	Import statements use aliases, dynamic imports, or barrel files that obscure the dependency chain	Run `dependency_analyzer.py --verbose` to inspect resolved module graph; refactor barrel re-exports into explicit imports
Coupling score always reads 0	Project has only one internal module (flat file structure with no subdirectories)	Organize code into multiple top-level directories so the analyzer can map inter-module relationships
Layer assignment shows all directories as "unknown"	Directory names do not match built-in layer indicators (e.g., `src/` instead of `services/`, `controllers/`)	Rename directories to conventional names or use the JSON output to manually map layers in your ADR
`--format plantuml` output renders incorrectly	Component names contain special characters (brackets, quotes) that PlantUML cannot escape	Rename directories to use alphanumeric and hyphen characters only
Dependency parser reports 0 dependencies	Package manifest file (`package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`) is missing or malformed	Verify the manifest exists in the project root and passes its native validation (`npm ls`, `pip check`, `go mod verify`)
Architecture assessment confidence below 30%	Project mixes multiple patterns or has a flat structure without clear layering	Pick a target pattern from `references/architecture_patterns.md` and restructure directories to match its conventions

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

Skill	Integration	Data Flow
`senior-backend`	Architecture patterns inform backend service boundaries and API contract design	Architect assessment output (detected pattern, layer assignments) feeds into backend module scaffolding
`senior-devops`	Deployment diagrams and technology detection drive infrastructure-as-code decisions	Deployment diagram type output + detected technologies list consumed by DevOps for Terraform/K8s config
`senior-security`	Dependency analysis surfaces packages that need security review	Dependency list JSON (`--output json`) passed to security scanning for CVE correlation
`senior-fullstack`	Architecture pattern selection determines which fullstack scaffold template to use	Pattern selection workflow result (e.g., modular monolith) maps to `project_scaffolder.py --type` flag
`code-reviewer`	Layer violation and god-class findings become review checklist items	`project_architect.py --output json` issues array integrated into code review checklists
`tech-stack-evaluator`	Technology detection results feed tech stack evaluation for upgrade/migration decisions	Detected technologies list and dependency versions inform stack evaluation decision matrices

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:

Flag	Short	Type	Default	Description
`project_path`	--	positional	required	Path to the project directory to scan
`--format`	`-f`	choice: `mermaid`, `plantuml`, `ascii`	`mermaid`	Output diagram format
`--type`	`-t`	choice: `component`, `layer`, `deployment`	`component`	Diagram type to generate
`--output`	`-o`	string	stdout	File path to write the diagram to
`--verbose`	`-v`	flag	off	Print scanning progress (components found, relationships, technologies)
`--json`	--	flag	off	Output raw scan results as JSON instead of a diagram

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:

Flag	Short	Type	Default	Description
`project_path`	--	positional	required	Path to the project directory to analyze
`--output`	`-o`	choice: `human`, `json`	`human`	Output format for the report
`--check`	--	choice: `all`, `circular`, `coupling`	`all`	Restrict analysis to a specific check; `circular` exits non-zero if cycles found, `coupling` exits non-zero if score >70
`--verbose`	`-v`	flag	off	Print progress details (package manager detected, dependency counts, module scan count)
`--save`	`-s`	string	none	Save JSON report to the specified file path

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:

Flag	Short	Type	Default	Description
`project_path`	--	positional	required	Path to the project directory to assess
`--output`	`-o`	choice: `human`, `json`	`human`	Output format for the assessment report
`--check`	--	choice: `all`, `pattern`, `layers`, `code`	`all`	Restrict to a specific check; `pattern` prints detected pattern only, `layers` exits non-zero on violations, `code` exits non-zero on warnings
`--verbose`	`-v`	flag	off	Print analysis progress (pattern detection, issue counts, violation counts)
`--save`	`-s`	string	none	Save JSON report to the specified file path

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.

senior-architect

Senior Architect

Table of Contents

Quick Start

Tools Overview

1. Architecture Diagram Generator

2. Dependency Analyzer

3. Project Architect

Decision Workflows

Database Selection Workflow

Architecture Pattern Selection Workflow

Monolith vs Microservices Decision

Reference Documentation

Tech Stack Coverage

Common Commands

Getting Help

Troubleshooting

Success Criteria

Scope & Limitations

Integration Points

Tool Reference

architecture_diagram_generator.py

dependency_analyzer.py

project_architect.py