Skip to content

Feature/java architecture analyst #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sunnyStefi wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Feature/java architecture analyst #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
abb189d
feat(agent): add Java Architecture Analyst agent
sunnyStefi Nov 26, 2025
b0decbd
docs(agent): register java-architecture-analyst in marketplace and fi…
sunnyStefi Nov 26, 2025
6b97923
docs: update README to include java-architecture-analyst plugin marke…
sunnyStefi Nov 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@
"name": "presentation-pdf-export",
"source": "./presentation-pdf-export",
"description": "PDF document generator for a HTML-based presentation generated by the presentation-manager skill."
},
{
"name": "java-architecture-analyst",
"source": "./java-architecture-analyst",
"description": "Java Architecture Analyst that delivers targeted architecture reports."
}
]
}
73 changes: 62 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,21 @@ A specialized plugin for generating professional PDF documents from HTML-based p

[View plugin documentation →](./presentation-pdf-export/README.md)

### java-architecture-analyst

An expert-level Java architecture analysis agent that produces structured, evidence-based architecture reports for Java/Spring Boot applications. Supports analysis across 18 specialized architectural layers.

**Key Features:**
- **18 Architectural Layers** - Comprehensive analysis from project overview to deployment operations
- **Evidence-Based Reports** - Detailed documentation with code references and findings
- **Multi-Layer Analysis** - Analyze multiple layers in a single command
- **Specialized Templates** - Each layer focuses on specific architectural concerns

**Available Agent:**
- **`java-architecture-analyst`** - AI-powered architecture analysis agent with configurable layer selection

[View plugin documentation →](./java-architecture-analyst/README.md)

## Installation

### Prerequisites
Expand Down Expand Up @@ -171,21 +186,51 @@ Use the `/plugin` menu to browse, enable, disable, or uninstall plugins interact
│ │ └── plugin.json # Plugin metadata
│ └── commands/
│ └── cc.md # Conventional Commit command
├── java-architecture-analyst/ # java-architecture-analyst plugin
│ ├── README.md # Plugin documentation
│ ├── .claude-plugin/
│ │ └── plugin.json # Plugin metadata
│ └── agents/
│ ├── java-architecture-analyst.md # Architecture analysis agent
│ ├── layers/ # 18 analysis layer templates
│ │ ├── project-overview.md
│ │ ├── technology-stack.md
│ │ ├── application-architecture.md
│ │ ├── architectural-patterns.md
│ │ ├── business-logic-architecture.md
│ │ ├── data-architecture.md
│ │ ├── requests-flow.md
│ │ ├── security-architecture.md
│ │ ├── configuration-management.md
│ │ ├── cross-cutting-concerns.md
│ │ ├── performance-scalability.md
│ │ ├── testing.md
│ │ ├── deployment-operations.md
│ │ ├── cost-resource-optimization.md
│ │ ├── key-design-decisions.md
│ │ ├── recommendations.md
│ │ ├── conclusions.md
│ │ └── appendices.md
│ ├── output-formats/
│ │ └── layer-medium-report.md
│ └── patterns/
│ └── active-developer.md
├── presentation-manager/ # presentation-manager plugin
│ ├── README.md # Plugin documentation
│ ├── .claude-plugin/
│ │ └── plugin.json # Plugin metadata
│ ├── skills/
│ │ └── SKILL.md # Presentation Manager skill
│ ├── commands/ # Command definitions
│ │ ├── new-slide.md
│ │ ├── add-topic.md
│ │ ├── list-slides.md
│ │ ├── preview.md
│ │ ├── validate-presentation.md
│ │ └── reorder-slides.md
│ └── assets/
│ └── shared-styles.css # Shared brand styles
│ │ ├── SKILL.md # Presentation Manager skill
│ │ ├── package.json # npm dependencies
│ │ └── templates/
│ │ └── shared-styles.css # Shared brand styles
│ └── commands/ # Command definitions
│ ├── new-slide.md
│ ├── add-topic.md
│ ├── list-slides.md
│ ├── preview.md
│ ├── validate-presentation.md
│ └── reorder-slides.md
└── presentation-pdf-export/ # presentation-pdf-export plugin
├── README.md # Plugin documentation
├── .claude-plugin/
Expand Down Expand Up @@ -232,7 +277,13 @@ For issues, questions, or feature requests, please open an issue in this reposit

## Version History

### 0.0.3 (Current)
### 0.0.4 (Current)
- Added `java-architecture-analyst` plugin for expert-level Java/Spring Boot architecture analysis
- Includes `java-architecture-analyst` agent with 18 specialized architectural layers
- Evidence-based reporting with code references and multi-layer analysis support
- Specialized templates for each architectural layer from project overview to deployment operations

### 0.0.3
- Added `presentation-pdf-export` plugin for generating professional PDFs from HTML presentations
- Includes `presentation-pdf-export` skill for automated PDF generation with Puppeteer
- Automatic dependency management and setup
Expand Down
34 changes: 34 additions & 0 deletions java-architecture-analyst/.claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
{
"name": "java-architecture-analyst",
"description": "Java Architecture Analyst that delivers targeted architecture reports",
"version": "0.0.1",
"author": {
"name": "Stefania Pozzi",
"email": "s.pozzi@sourcelabs.nl"
},
"keywords": [
"java",
"architecture",
"analysis",
"code-review",
"project-overview",
"application-architecture",
"architectural-patterns",
"business-logic-architecture",
"data-architecture",
"security-architecture",
"performance-scalability",
"testing",
"deployment-operations",
"configuration-management",
"cross-cutting-concerns",
"requests-flow",
"technology-stack",
"key-design-decisions",
"cost-resource-optimization",
"recommendations",
"conclusions",
"appendices"
],
"agents": ["./agents/java-architecture-analyst.md"]
}
231 changes: 231 additions & 0 deletions java-architecture-analyst/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,231 @@
<div align="center">

# Java Architecture Analyst Agent

[![Agent Type](https://img.shields.io/badge/🤖_Agent-Java_Architecture_Analyst-8b5cf6?style=for-the-badge&labelColor=4c1d95)](agents)
[![Model](https://img.shields.io/badge/🧠_Model-Claude_Sonnet-3b82f6?style=for-the-badge&labelColor=1e40af)](agents)

![Version](https://img.shields.io/badge/version-0.0.1-blue?style=flat-square)
![Layers](https://img.shields.io/badge/layers-18-informational?style=flat-square)
![Status](https://img.shields.io/badge/status-active-success?style=flat-square)

</div>

---

## ✨ Overview
An expert-level Java architecture analysis agent that produces structured architecture reports for Java/Spring Boot applications.
It generates evidence-based documentation tailored to specific architectural layers.

## 🔨 Usage

### Basic Syntax
```
use java-architecture-analyst with variable layer-name=<layer-name>
```

### Examples

#### Security Review, Data Layer Analysis
```
use java-architecture-analyst with variable layer-name=security-architecture,data-architecture
```
### Default Behavior
If no `layer-name` is specified, defaults to `project-overview`.

---

## 📚 Available Layer Templates

The agent supports analysis across **18 architectural layers**. Each layer produces a specialized report focused on specific architectural concerns.

| Layer Name | Focus Area | Best For |
|------------|------------|----------|
| `project-overview` | High-level system architecture, tech stack | 🎯 Start here - holistic view |
| `application-architecture` | Application structure, component organization | 📦 Understanding code organization |
| `architectural-patterns` | Design patterns, architectural styles | 🏗️ Pattern identification & usage |
| `business-logic-architecture` | Domain model, business rules, services | 💼 Core business logic analysis |
| `data-architecture` | Data models, persistence, database design | 🗄️ Data flow & storage strategy |
| `security-architecture` | Authentication, authorization, security controls | 🔒 Security posture assessment |
| `performance-scalability` | Performance characteristics, scaling patterns | ⚡ Performance optimization |
| `testing` | Test strategy, coverage, quality assurance | ✅ Testing maturity assessment |
| `deployment-operations` | Deployment, monitoring, observability | 🚀 DevOps & operations review |
| `configuration-management` | Configuration strategy, profiles, environments | ⚙️ Config management practices |
| `cross-cutting-concerns` | Logging, error handling, transactions, AOP | 🔄 Cross-cutting implementations |
| `requests-flow` | Request processing, API interactions | 🔀 Request/response patterns |
| `technology-stack` | Technology choices, dependencies, versions | 🛠️ Tech stack deep dive |
| `key-design-decisions` | ADRs, critical design choices | 📋 Decision documentation |
| `cost-resource-optimization` | Resource utilization, cost considerations | 💰 Efficiency & cost analysis |
| `recommendations` | Improvement suggestions, refactoring opportunities | 💡 Actionable improvements |
| `conclusions` | Summary findings, risk assessment, health | 📊 Overall assessment |
| `appendices` | Supporting information, references | 📚 Additional documentation |

---

## 🎯 Agent Capabilities

### 🎓 Expertise Areas

| Domain | Specializations |
|--------|----------------|
| **Enterprise Architecture** | Patterns, principles, SOLID, clean architecture |
| **Spring Ecosystem** | Spring Boot, Spring Framework, Spring Data, Spring Security, Spring Cloud |
| **Cloud-Native** | 12-factor apps, microservices, containerization, Kubernetes |
| **Distributed Systems** | Service decomposition, resilience patterns, event-driven architectures, messaging |
| **Domain-Driven Design** | DDD patterns, bounded contexts, aggregates, domain events |
| **Performance** | Optimization strategies, caching, async processing, load testing |
| **Security** | Security architecture, OWASP, compliance frameworks, threat modeling |
| **DevOps** | CI/CD pipelines, IaC, deployment strategies, GitOps |

### ✨ Analysis Features

| Feature | Description |
|---------|-------------|
| **Evidence-Based** | References actual code, configuration files, and dependencies |
| **Template-Driven** | Follows consistent structure across all reports |
| **Technical Depth** | Tailored for senior engineers with appropriate detail level |
| **Visual Diagrams** | Includes architectural diagrams (ASCII art, Mermaid) |
| **Best Practices** | Aligned with industry standards and quality guidelines |
| **Actionable** | Provides concrete, prioritized recommendations |

---

## 📄 Output

### Report Structure
Each generated report follows a predefined template specific to the layer being analyzed, ensuring:

| Quality Attribute | Description |
|-------------------|-------------|
| **Consistency** | Uniform structure across different analyses |
| **Completeness** | Full coverage of the architectural concern |
| **Depth** | Appropriate level of detail for senior engineers |
| **Actionability** | Concrete, implementable recommendations |

### Report Location
```
docs/architecture-reports/<layer-name>-YYYY-MM-DD.md
```

**Example outputs:**
- `docs/architecture-reports/project-overview-2025-11-26.md`
- `docs/architecture-reports/security-architecture-2025-11-26.md`

### Report Format

| Component | Details |
|-----------|---------|
| **Format** | Markdown (`.md`) for version control compatibility |
| **Structure** | Hierarchical sections based on layer template |
| **Code Examples** | Configuration snippets, code samples with syntax highlighting |
| **Diagrams** | ASCII art or Mermaid syntax for visual representation |
| **References** | Source file paths and line numbers for traceability |

---

## ✅ Quality Standards

The agent applies quality standards from the **active-developer** pattern:

| Standard | Implementation |
|----------|----------------|
| **Accuracy** | Precise technical details with source verification |
| **Evidence-Based** | All conclusions backed by code/config references |
| **Clarity** | Professional technical writing for senior engineers |
| **Actionability** | Prioritized recommendations by impact and effort |
| **Risk Assessment** | Identified risks with mitigation strategies |

---

## 🔗 Integration

### IDE Integration
The agent integrates seamlessly with Claude in IDEs through the Claude plugin:
- ✅ Visual Studio Code
- ✅ JetBrains IDEs (IntelliJ IDEA, WebStorm, etc.)

### Version Control Benefits

| Benefit | Description |
|---------|-------------|
| 📝 **Living Documentation** | Evolves with the codebase, stays current |
| 📜 **Historical Record** | Tracks architectural decisions over time |
| 🎓 **Onboarding Material** | Accelerates new team member ramp-up |
| 🔍 **Review Reference** | Supports architectural reviews and audits |
| 🤝 **Team Alignment** | Creates shared understanding of architecture |

---

## 💡 Tips for Effective Use

| # | Tip | Rationale |
|---|-----|-----------|
| 1️⃣ | **Start with project-overview** | Get a holistic understanding before diving deep |
| 2️⃣ | **Deep dive into specific layers** | Focus on areas relevant to your current work |
| 3️⃣ | **Regenerate after major changes** | Keep documentation current and accurate |
| 4️⃣ | **Combine multiple layer reports** | Build comprehensive architectural documentation |
| 5️⃣ | **Use recommendations layer** | Identify improvement opportunities systematically |
| 6️⃣ | **Review conclusions layer** | Assess overall architectural health regularly |
| 7️⃣ | **Version control the reports** | Track architectural evolution over time |
| 8️⃣ | **Share with the team** | Create shared understanding and alignment |

---

## 🎬 Example Workflows

### 📋 Scenario 1: Complete Architecture Assessment
```bash
# 1. Generate project overview
# 2. Analyze application structure
# 3. Review architectural patterns
# 4. Get recommendations
# 5. Review overall conclusions
use java-architecture-analyst with variable layer-name=project-overview,application-architecture,architectural-patterns,recommendations,conclusions
```

### 🔒 Scenario 2: Security Audit
```bash
# 1. Security architecture review
# 2. Check cross-cutting concerns (error handling, logging)
# 3. Review configuration management
# 4. Get security recommendations
use java-architecture-analyst with variable layer-name=security-architecture,cross-cutting-concerns,configuration-management,recommendations
```

### 🏗️ Scenario 3: Refactoring Planning
```bash
# 1. Review current patterns
# 2. Analyze business logic structure
# 3. Review key design decisions
# 4. Get refactoring recommendations
use java-architecture-analyst with variable layer-name=architectural-patterns,business-logic-architecture,key-design-decisions,recommendations
```

---

## 📋 Requirements

| Category | Details |
|----------|---------|
| **Project Type** | Java Spring Boot application with standard Maven/Gradle structure |
| **Access** | Source code, configuration files, and build files |

---

## 📚 Additional Resources

- **Agent Definition**: `.claude/agents/java-architecture-analyst.md`
- **Layer Templates**: `.claude/agents/layers/`
- **Output Formats**: `.claude/agents/output-formats/`
- **Quality Patterns**: `.claude/agents/patterns/`

---

<div align="center">

**Last Updated:** November 26, 2025 | **Agent Version:** 1.0 | **Minimum Claude Version:** Sonnet

Made with ❤️ for Java & Spring Boot architects

</div>

Loading