You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Architecture intelligence for Android and Kotlin Multiplatform Gradle builds.
3
+
**Architecture Intelligence for Android & Kotlin Multiplatform**
4
4
5
-
Gradle Lighthouse audits module structure, dependency hygiene, security, build performance, and code health directly from your Gradle project. It transforms audit findings into a transparent architectural health model with industry benchmarking.
5
+
Gradle Lighthouse analyzes your Gradle project, detects architectural risks, evaluates build health, and generates actionable recommendations to improve maintainability, scalability, and developer productivity.
`gradle-lighthouse` is an enterprise-grade Gradle diagnostic engine designed for teams that want more than simple lint findings. It measures **Architectural Health** by analyzing your project's structure, dependencies, and build configuration against industry standards and reference benchmarks like *Now in Android* and *Signal*.
24
+
* Which modules are slowing development
25
+
* Where architectural boundaries are leaking
26
+
* Why builds are becoming slower
27
+
* Which issues deserve attention first
28
+
* How their architecture evolves over time
29
+
30
+
Gradle Lighthouse answers those questions with a single audit.
31
+
32
+
```bash
33
+
./gradlew lighthouseAudit lighthouseAggregate
34
+
```
18
35
19
36
---
20
37
21
-
## Key Features
38
+
## What You Get
39
+
40
+
### Architectural Health Score
41
+
42
+
A transparent health model that evaluates:
43
+
44
+
* Architecture
45
+
* Security
46
+
* Build Performance
47
+
* Dependency Hygiene
48
+
* Complexity
49
+
* Modernization
50
+
* Quality
51
+
* Application Size
52
+
53
+
Instead of showing hundreds of findings, Lighthouse highlights the areas that have the greatest architectural impact.
54
+
55
+
### Path to 90
56
+
57
+
Lighthouse generates an improvement roadmap showing which fixes produce the largest score gains.
Compare your project against architectural reference snapshots generated by Lighthouse.
89
+
90
+
Benchmarking provides context for your score and helps teams understand where they stand relative to similar projects.
22
91
23
-
***Modern Health Score Engine**: A category-weighted scoring model (v2) that uses square root dampening to provide fair and actionable scores for repositories of any size.
24
-
***Architecture Health Breakdown**: Detailed dashboards showing scores for Architecture, Security, Performance, Build Performance, Complexity, and more.
25
-
***Industry Benchmarking**: Compare your project against industry giants. See where you rank in the top percentiles of Android projects globally.
26
-
***Project Persona Classification**: Automatically identifies if your project is a *Modular Monolith*, *Large Android App*, or *KMP Product* for accurate peer-group comparison.
27
-
***Path To 90**: An automated architectural roadmap that estimates the score gain for every fix, helping you prioritize engineering work.
28
-
***Galaxy Graph**: An interactive, canvas-based module dependency visualizer with cycle detection and "Sandbox Mode" for refactoring simulations.
29
-
***Baseline System**: Record current technical debt and focus your team only on *new* regressions.
30
-
***Lighthouse Fix**: Automatically apply performance and best-practice fixes to your project configuration.
31
-
***CI/CD Native**: Exports results as self-contained HTML, SARIF (for GitHub Security), and JUnit XML.
See which industry reference projects (Signal, NiA, etc.) are currently loaded into your engine:
172
+
Output:
173
+
174
+
```text
175
+
build/reports/lighthouse/benchmark.json
176
+
```
177
+
178
+
### View Loaded Benchmarks
81
179
82
180
```bash
83
181
./gradlew lighthouseBenchmarkStatus
@@ -87,42 +185,37 @@ See which industry reference projects (Signal, NiA, etc.) are currently loaded i
87
185
88
186
## Scoring Philosophy
89
187
90
-
Lighthouse moves away from "finding counters" toward a **transparent architectural model**:
188
+
Gradle Lighthouse focuses on architectural health rather than issue counts.
91
189
92
-
1.**Category Scoring**: Each finding belongs to a domain (e.g., Security). Scores are calculated per category using a square root deduction curve ($100 - K \times \sqrt{RawImpact}$) to prevent score collapse in large repos.
93
-
2.**Weakest Link Logic**: Overall score is the average of the weighted mean and the poorest category. Excellent build performance cannot mask critical security failures.
94
-
3.**Relative Benchmarking**: Your score is context-aware. A 75 in a 200-module enterprise app is often "Stronger" than a 90 in a small monolith.
95
-
4.**Data-Driven Snapshots**: All industry benchmarks are generated by Lighthouse itself, ensuring comparisons are always "apples-to-apples."
190
+
### Category-Based Scoring
96
191
97
-
---
192
+
Each finding contributes to a specific architectural domain.
193
+
194
+
### Weakest-Link Principle
98
195
99
-
## FAQ
196
+
A project cannot be considered healthy if a critical category is failing.
100
197
101
-
### Why is my score low?
102
-
Check the **Architecture Health Breakdown**. The "Weakest Area" indicator will show you which domain (e.g., Complexity) is dragging down your score.
198
+
### Actionable Feedback
103
199
104
-
### Why does Signal score differently than NIA?
105
-
Each project has a different structural profile. Signal, being a mature communications app, may prioritize Security over NiA's optimized Architecture.
200
+
Every deduction is traceable to findings and improvement opportunities.
106
201
107
-
### How are benchmarks generated?
108
-
By running `./gradlew lighthouseExportBenchmark` on the target repositories. No manual score editing is allowed.
202
+
### Benchmark-Aware Context
109
203
110
-
### Can I create my own benchmark registry?
111
-
Yes. Drop any generated `benchmark.json` files into a `benchmarks/` directory at your project root, and Lighthouse will automatically include them in your comparisons.
204
+
Scores are evaluated relative to project structure and benchmark baselines.
112
205
113
206
---
114
207
115
208
## Documentation
116
209
117
-
| Document | Content|
118
-
|----------|---------|
119
-
|[Architecture](docs/architecture.md)| System overview and execution flow |
120
-
|[Scoring Model](docs/scoring-model.md)|Weights, grades, and weakest-link logic|
121
-
|[Benchmarking](docs/benchmarking.md)| Percentiles and snapshot generation|
0 commit comments