Senior Architect

What Is Senior Architect?

Senior Architect is a specialized Claude Code skill designed to assist engineering teams with system architecture design, technical decision-making, and architecture documentation. With a focus on real-world software development scenarios, the Senior Architect skill provides a comprehensive toolkit for tasks such as designing robust system architectures, evaluating the merits of microservices versus monolithic architectures, generating visual architecture diagrams, analyzing project dependencies, and making informed decisions about databases, scalability, and tech stacks. Whether you are planning a new system, reviewing existing architecture, or drafting Architecture Decision Records (ADRs), Senior Architect empowers developers and architects with actionable insights and automation to streamline complex architectural processes.

Why Use Senior Architect?

Modern software systems are increasingly complex, requiring careful consideration of architecture patterns, technology stacks, scalability strategies, and dependency management. Senior Architect addresses these challenges by delivering:

• Rapid architecture visualization: Automatically generate architecture diagrams in multiple formats, enabling teams to communicate complex designs clearly.
• Informed decision support: Evaluate architectural trade-offs such as microservices vs. monolith, database selection, and dependency analysis based on best practices.
• Standardized documentation: Generate ADRs and system design reviews that align with industry standards, ensuring consistency across projects.
• Efficiency and accuracy: Automate repetitive or error-prone architecture tasks, reducing manual effort and minimizing the risk of oversight.

By integrating Senior Architect into your engineering workflow, you can accelerate system design, facilitate better collaboration, and make high-confidence technical decisions.

How to Get Started

Getting started with Senior Architect is straightforward. The toolkit is distributed as a collection of Python scripts, enabling command-line usage for architecture analysis and diagram generation.

1. Clone the repository:

   bash

   git clone https://github.com/alirezarezvani/claude-skills.git
   cd claude-skills/engineering-team/senior-architect

2. Install dependencies:

   Most scripts require Python 3.8+ and a few common packages. Install them using:

   bash

   pip install -r requirements.txt

3. Generate an architecture diagram:

   bash

   python scripts/architecture_diagram_generator.py ./my-project --format mermaid

   This will parse your project and generate a Mermaid-format diagram file.

4. Analyze dependencies:

   bash

   python scripts/dependency_analyzer.py ./my-project --output json

   The output will summarize dependency issues, cycles, or version mismatches.

5. Explore further features:
   Review the included scripts and documentation for advanced features such as tech stack evaluation and system design review automation.

Key Features

1. Architecture Diagram

Generator

Visualizing architecture is critical for both design and communication. The architecture_diagram_generator.py script automates this process. It parses your project structure and outputs diagrams in various formats, including Mermaid, PlantUML, and ASCII.

Example:

python scripts/architecture_diagram_generator.py ./my-project --format plantuml

Sample Mermaid Output:

graph TD
    Client --> API
    API --> Database
    API --> AuthService
    AuthService --> Database

2. Dependency

Analyzer

Understanding and managing dependencies is essential for maintainability and scalability. The dependency_analyzer.py script scans your project for dependency issues such as cyclic dependencies, outdated packages, or conflicting versions.

Example:

python scripts/dependency_analyzer.py ./my-project --output json

Sample JSON Output:

{
    "cycles": [["moduleA", "moduleB", "moduleA"]],
    "outdated": ["requests"],
    "conflicts": []
}

3. Project

Architect

The toolkit includes modules for generating and reviewing Architecture Decision Records (ADRs), evaluating tech stacks, and providing recommendations for database selection, scalability planning, and system design patterns. These features help formalize decision-making and ensure alignment with organizational standards.

Best Practices

• Integrate early: Use Senior Architect tools at the start of your project to establish sound architectural foundations.
• Automate regularly: Schedule dependency analyses and architecture diagram generation as part of your CI/CD pipeline to catch issues early.
• Document decisions: Leverage the ADR features to record architectural choices, aiding future maintainers and audits.
• Visualize changes: Regenerate diagrams after major changes to keep documentation synchronized with code.

Important Notes

• Project compatibility: While the scripts are designed to be broadly compatible, results may vary depending on the project’s structure and language. Customization may be required for non-standard layouts.
• Diagram output formats: Mermaid and PlantUML provide the best support for complex diagrams. ASCII output is suitable for console-based review but may lack detail.
• Security: Always review generated ADRs and dependency reports for sensitive information before sharing externally.
• Maintenance: Keep the Senior Architect toolkit updated to benefit from bug fixes and new features as the repository evolves.

By adopting Senior Architect, engineering teams can significantly enhance architectural rigor, boost productivity, and ensure that technical decisions are well-documented and defensible.