architecture-review

Name: architecture-review
Author: decebals

686stars133forks

How to install architecture-review?

decebals/claude-code-java/architecture-review

$npx -y skills add decebals/claude-code-java --skill architecture-review

Installs into the current project.

Summary

Analyze Java project architecture at macro level - package structure, module boundaries, dependency direction, and layering. Use when user asks "review architecture", "check structure", "package organization", or when evaluating if a codebase follows clean architecture principles

Files · 1

View on GitHub

SKILL.md

1	# Architecture Review Skill
2
3	Analyze project structure at the macro level - packages, modules, layers, and boundaries.
4
5	## When to Use
6	- User asks "review the architecture" / "check project structure"
7	- Evaluating package organization
8	- Checking dependency direction between layers
9	- Identifying architectural violations
10	- Assessing clean/hexagonal architecture compliance
11
12	---
13
14	## Quick Reference: Architecture Smells
15
16	\| Smell \| Symptom \| Impact \|
17	\|-------\|---------\|--------\|
18	\| Package-by-layer bloat \| `service/` with 50+ classes \| Hard to find related code \|
19	\| Domain → Infra dependency \| Entity imports `@Repository` \| Core logic tied to framework \|
20	\| Circular dependencies \| A → B → C → A \| Untestable, fragile \|
21	\| God package \| `util/` or `common/` growing \| Dump for misplaced code \|
22	\| Leaky abstractions \| Controller knows SQL \| Layer boundaries violated \|
23
24	---
25
26	## Package Organization Strategies
27
28	### Package-by-Layer (Traditional)
29
30	```
31	com.example.app/
32	├── controller/
33	│ ├── UserController.java
34	│ ├── OrderController.java
35	│ └── ProductController.java
36	├── service/
37	│ ├── UserService.java
38	│ ├── OrderService.java
39	│ └── ProductService.java
40	├── repository/
41	│ ├── UserRepository.java
42	│ ├── OrderRepository.java
43	│ └── ProductRepository.java
44	└── model/
45	├── User.java
46	├── Order.java
47	└── Product.java
48	```
49
50	Pros: Familiar, simple for small projects
51	Cons: Scatters related code, doesn't scale, hard to extract modules
52
53	### Package-by-Feature (Recommended)
54
55	```
56	com.example.app/
57	├── user/
58	│ ├── UserController.java
59	│ ├── UserService.java
60	│ ├── UserRepository.java
61	│ └── User.java
62	├── order/
63	│ ├── OrderController.java
64	│ ├── OrderService.java
65	│ ├── OrderRepository.java
66	│ └── Order.java
67	└── product/
68	├── ProductController.java
69	├── ProductService.java
70	├── ProductRepository.java
71	└── Product.java
72	```
73
74	Pros: Related code together, easy to extract, clear boundaries
75	Cons: May need shared kernel for cross-cutting concerns
76
77	### Hexagonal/Clean Architecture
78
79	```
80	com.example.app/
81	├── domain/ # Pure business logic (no framework imports)
82	│ ├── model/
83	│ │ └── User.java
84	│ ├── port/
85	│ │ ├── in/ # Use cases (driven)
86	│ │ │ └── CreateUserUseCase.java
87	│ │ └── out/ # Repositories (driving)
88	│ │ └── UserRepository.java
89	│ └── service/
90	│ └── UserDomainService.java
91	├── application/ # Use case implementations
92	│ └── CreateUserService.java
93	├── adapter/
94	│ ├── in/
95	│ │ └── web/
96	│ │ └── UserController.java
97	│ └── out/
98	│ └── persistence/
99	│ ├── UserJpaRepository.java
100	│ └── UserEntity.java
101	└── config/
102	└── BeanConfiguration.java
103	```
104
105	Key rule: Dependencies point inward (adapters → application → domain)
106
107	---
108
109	## Dependency Direction Rules
110
111	### The Golden Rule
112
113	```
114	┌─────────────────────────────────────────┐
115	│ Frameworks │ ← Outer (volatile)
116	├─────────────────────────────────────────┤
117	│ Adapters (Web, DB) │
118	├─────────────────────────────────────────┤
119	│ Application Services │
120	├─────────────────────────────────────────┤
121	│ Domain (Core Logic) │ ← Inner (stable)
122	└─────────────────────────────────────────┘
123
124	Dependencies MUST point inward only.
125	Inner layers MUST NOT know about outer layers.
126	```
127
128	### Violations to Flag
129
130	```java
131	// ❌ Domain depends on infrastructure
132	package com.example.domain.model;
133
134	import org.springframework.data.jpa.repository.JpaRepository; // Framework leak!
135	import javax.persistence.Entity; // JPA in domain!
136
137	@Entity
138	public class User {
139	// Domain polluted with persistence concerns
140	}
141
142	// ❌ Domain depends on adapter
143	package com.example.domain.service;
144
145	import com.example.adapter.out.persistence.UserJpaRepository; // Wrong direction!
146
147	// ✅ Domain defines port, adapter implements
148	package com.example.domain.port.out;
149
150	public interface UserRepository { // Pure interface, no JPA
151	User findById(UserId id);
152	void save(User user);
153	}
154	```
155
156	---
157
158	## Architecture Review Checklist
159
160	### 1. Package Structure
161	- [ ] Clear organization strategy (by-layer, by-feature, or hexagonal)
162	- [ ] Consistent naming across modules
163	- [ ] No `util/` or `common/` packages growing unbounded
164	- [ ] Feature packages are cohesive (related code together)
165
166	### 2. Dependency Direction
167	- [ ] Domain has ZERO framework imports (Spring, JPA, Jackson)
168	- [ ] Adapters depend on domain, not vice versa
169	- [ ] No circular dependencies between packages
170	- [ ] Clear dependency hierarchy
171
172	### 3. Layer Boundaries
173	- [ ] Controllers don't contain business logic
174	- [ ] Servi

People who liked this also viewed

6 picks

Type

architecture-review

686stars133forks

View on GitHub

How to install architecture-review?

decebals/claude-code-java/architecture-review

$npx -y skills add decebals/claude-code-java --skill architecture-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Architecture Review Skill
2
3	Analyze project structure at the macro level - packages, modules, layers, and boundaries.
4
5	## When to Use
6	- User asks "review the architecture" / "check project structure"
7	- Evaluating package organization
8	- Checking dependency direction between layers
9	- Identifying architectural violations
10	- Assessing clean/hexagonal architecture compliance
11
12	---
13
14	## Quick Reference: Architecture Smells
15
16	\| Smell \| Symptom \| Impact \|
17	\|-------\|---------\|--------\|
18	\| Package-by-layer bloat \| `service/` with 50+ classes \| Hard to find related code \|
19	\| Domain → Infra dependency \| Entity imports `@Repository` \| Core logic tied to framework \|
20	\| Circular dependencies \| A → B → C → A \| Untestable, fragile \|
21	\| God package \| `util/` or `common/` growing \| Dump for misplaced code \|
22	\| Leaky abstractions \| Controller knows SQL \| Layer boundaries violated \|
23
24	---
25
26	## Package Organization Strategies
27
28	### Package-by-Layer (Traditional)
29
30	```
31	com.example.app/
32	├── controller/
33	│ ├── UserController.java
34	│ ├── OrderController.java
35	│ └── ProductController.java
36	├── service/
37	│ ├── UserService.java
38	│ ├── OrderService.java
39	│ └── ProductService.java
40	├── repository/
41	│ ├── UserRepository.java
42	│ ├── OrderRepository.java
43	│ └── ProductRepository.java
44	└── model/
45	├── User.java
46	├── Order.java
47	└── Product.java
48	```
49
50	Pros: Familiar, simple for small projects
51	Cons: Scatters related code, doesn't scale, hard to extract modules
52
53	### Package-by-Feature (Recommended)
54
55	```
56	com.example.app/
57	├── user/
58	│ ├── UserController.java
59	│ ├── UserService.java
60	│ ├── UserRepository.java
61	│ └── User.java
62	├── order/
63	│ ├── OrderController.java
64	│ ├── OrderService.java
65	│ ├── OrderRepository.java
66	│ └── Order.java
67	└── product/
68	├── ProductController.java
69	├── ProductService.java
70	├── ProductRepository.java
71	└── Product.java
72	```
73
74	Pros: Related code together, easy to extract, clear boundaries
75	Cons: May need shared kernel for cross-cutting concerns
76
77	### Hexagonal/Clean Architecture
78
79	```
80	com.example.app/
81	├── domain/ # Pure business logic (no framework imports)
82	│ ├── model/
83	│ │ └── User.java
84	│ ├── port/
85	│ │ ├── in/ # Use cases (driven)
86	│ │ │ └── CreateUserUseCase.java
87	│ │ └── out/ # Repositories (driving)
88	│ │ └── UserRepository.java
89	│ └── service/
90	│ └── UserDomainService.java
91	├── application/ # Use case implementations
92	│ └── CreateUserService.java
93	├── adapter/
94	│ ├── in/
95	│ │ └── web/
96	│ │ └── UserController.java
97	│ └── out/
98	│ └── persistence/
99	│ ├── UserJpaRepository.java
100	│ └── UserEntity.java
101	└── config/
102	└── BeanConfiguration.java
103	```
104
105	Key rule: Dependencies point inward (adapters → application → domain)
106
107	---
108
109	## Dependency Direction Rules
110
111	### The Golden Rule
112
113	```
114	┌─────────────────────────────────────────┐
115	│ Frameworks │ ← Outer (volatile)
116	├─────────────────────────────────────────┤
117	│ Adapters (Web, DB) │
118	├─────────────────────────────────────────┤
119	│ Application Services │
120	├─────────────────────────────────────────┤
121	│ Domain (Core Logic) │ ← Inner (stable)
122	└─────────────────────────────────────────┘
123
124	Dependencies MUST point inward only.
125	Inner layers MUST NOT know about outer layers.
126	```
127
128	### Violations to Flag
129
130	```java
131	// ❌ Domain depends on infrastructure
132	package com.example.domain.model;
133
134	import org.springframework.data.jpa.repository.JpaRepository; // Framework leak!
135	import javax.persistence.Entity; // JPA in domain!
136
137	@Entity
138	public class User {
139	// Domain polluted with persistence concerns
140	}
141
142	// ❌ Domain depends on adapter
143	package com.example.domain.service;
144
145	import com.example.adapter.out.persistence.UserJpaRepository; // Wrong direction!
146
147	// ✅ Domain defines port, adapter implements
148	package com.example.domain.port.out;
149
150	public interface UserRepository { // Pure interface, no JPA
151	User findById(UserId id);
152	void save(User user);
153	}
154	```
155
156	---
157
158	## Architecture Review Checklist
159
160	### 1. Package Structure
161	- [ ] Clear organization strategy (by-layer, by-feature, or hexagonal)
162	- [ ] Consistent naming across modules
163	- [ ] No `util/` or `common/` packages growing unbounded
164	- [ ] Feature packages are cohesive (related code together)
165
166	### 2. Dependency Direction
167	- [ ] Domain has ZERO framework imports (Spring, JPA, Jackson)
168	- [ ] Adapters depend on domain, not vice versa
169	- [ ] No circular dependencies between packages
170	- [ ] Clear dependency hierarchy
171
172	### 3. Layer Boundaries
173	- [ ] Controllers don't contain business logic
174	- [ ] Servi

People who liked this also viewed

6 picks

Type