senior-architect

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: senior-architect
description: >
  System architecture design and review. Use when designing architecture, evaluating
  microservices vs monolith, writing ADRs, choosing a database, planning for scalability,
  reviewing system design, or generating architecture diagrams.
license: MIT + Commons Clause
metadata:
  version: 1.1.0
  author: borghei
  category: engineering
  domain: system-design
  updated: 2026-06-17
  tags: [system-design, distributed-systems, architecture, adr, scalability]
---
# Senior Architect

Architecture design and analysis tools for making informed technical decisions: visualize system structure, analyze dependencies and coupling, detect architectural patterns, and run decision workflows for databases, patterns, and monolith-vs-microservices trade-offs.

## Core Capabilities

- **Diagram generation** — produce component, layer, and deployment diagrams in Mermaid, PlantUML, or ASCII from a project directory.
- **Dependency analysis** — map the dependency tree, score coupling (0-100), and detect circular dependencies across npm, pip, Poetry, Go modules, and Cargo.
- **Pattern detection** — assess an existing codebase for layered/MVC/hexagonal/clean/microservices patterns, layer violations, god classes, and mixed concerns.
- **Database selection** — match data characteristics, scale, and consistency needs to SQL/NoSQL options with an ADR template.
- **Pattern & topology selection** — choose an architecture pattern by team size, deployment, and data-boundary requirements.
- **Monolith vs microservices** — apply decision checklists and a modular-monolith-first hybrid strategy.

## When to Use

- Designing a new system or refactoring existing architecture.
- Evaluating microservices vs monolith, or choosing a database.
- Writing an ADR, planning for scalability, or reviewing a system design.
- Generating architecture diagrams for documentation or team review.

## Clarify First

Before generating diagrams or an assessment, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Project root** — the codebase directory to analyze (drives pattern detection, dependency scoring, and diagram contents)
- [ ] **Diagram type & format** — component / layer / deployment in Mermaid / PlantUML / ASCII (sets what the generator emits)
- [ ] **Architecture decision in question** — e.g. database choice or monolith vs microservices (selects the decision workflow and ADR)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

## Tools

| Tool | Purpose | Command |
|------|---------|---------|
| `architecture_diagram_generator.py` | Generate component/layer/deployment diagrams from project structure | `python scripts/architecture_diagram_generator.py ./project --format mermaid --type component` |
| `dependency_analyzer.py` | Score coupling and find circular dependencies across package managers | `python scripts/dependency_analyzer.py ./project --output json --check circular` |
| `project_architect.py` | Detect architecture pattern, layer violations, and code smells | `python scripts/project_architect.py ./project --check layers --verbose` |

Run any script with `--help` for full flags.

## References

Load the reference that matches the task — keep this file lean and pull detail on demand:

- **[references/architecture_patterns.md](references/architecture_patterns.md)** — 9 architecture patterns (monolith, modular monolith, microservices, event-driven, CQRS, event sourcing, hexagonal, clean, API gateway) with trade-offs and code examples. Read when asked "which pattern?", "microservices vs monolith", "event-driven", or "CQRS".
- **[references/system_design_workflows.md](references/system_design_workflows.md)** — 6 step-by-step workflows: design interview, capacity planning, API design, database schema design, scalability assessment, migration planning. Read when asked "how to design?", "capacity plann