# androidpoet/compose-guard architecture

> Architecture diagram of the GitHub repository androidpoet/compose-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/androidpoet/compose-guard
- Repository: https://github.com/androidpoet/compose-guard

## Overview

ComposeGuard is a multi-module Kotlin repository centered on an IntelliJ Platform plugin for Android Studio/IntelliJ IDEA, with a small Android sample app used to demonstrate the plugin’s findings.

##### Top-level architecture

The repository is organized into three practical boundaries:

1. **`compose-guard/`** — the core IntelliJ/Android Studio plugin
2. **`app/`** — an Android demo application that showcases Compose rule violations
3. **`sample/`** — standalone sample source used by tests and rule demonstrations

Supporting this are root Gradle build files, CI workflows, and packaging assets.

---

##### 1) Plugin module: `compose-guard/`

This is the main product. It is packaged as an IntelliJ Platform plugin defined by `src/main/resources/META-INF/plugin.xml`.

###### Core responsibility
The plugin analyzes Kotlin source files containing Jetpack Compose code and surfaces rule violations directly in the IDE.

###### Main functional subsystems

- **Rule engine**
  - Located under `rules/`
  - Contains the domain model for a “Compose rule” and the rule registry
  - Rules are grouped by category:
    - `naming`
    - `modifiers`
    - `parameters`
    - `composables`
    - `state`
    - `effects`
    - `performance`
    - `stricter`
  - The registry acts as the catalog of all supported rules and is the main source of truth for what the plugin can detect.

- **IDE analysis and presentation**
  - `inspection/`
    - Implements IDE inspections for rule violations
    - Includes a suppressor for built-in inspections related to ComposeGuard’s own findings
  - `annotator/`
    - Adds inline annotations/highlighting in editor text
  - `inlay/`
    - Provides inlay hints next to code, likely for compact rule badges/status indicators
  - `linemarker/`
    - Adds gutter markers for composable functions, matching the README’s red/orange/gray/green status indicators

- **Quick fix system**
  - `quickfix/`
  - Each rule category has dedicated code actions such as:
    - rename composable / parameter
    - add modifier or default value
    - wrap state in `remember`
    - move modifier / reorder parameters
    - add key/contentType to lazy lists
    - use lifecycle-aware collection
    - suppress specific rule
  - These are the remediation path from a detected violation back to editable source code

- **Settings and configuration**
  - `settings/`
  - Manages global enablement, display options, category-level toggles, individual rule toggles, and experimental rules
  - This is the main boundary between plugin behavior and user preference

- **Statistics and dashboard**
  - `statistics/`
  - Collects violation counts and aggregates them for a tool window dashboard
  - `toolwindow/`
  - Exposes the “ComposeGuard Statistics” panel in the IDE
  - This subsystem is separate from code analysis: it consumes violation data and presents project-wide trends

###### Data flow inside the plugin

The likely flow is:

1. **IDE opens or edits Kotlin files**
2. **Plugin hooks into IDE analysis points**
   - inspections
   - annotators
   - inlay providers
   - line marker providers
3. **Compose-specific rules inspect PSI/UAST-like source structure**
4. **Violations are created with severity and metadata**
5. **Violations are rendered in multiple IDE surfaces**
   - editor highlighting
   - gutter icons
   - inline hints
   - tooltips
6. **If the user invokes a fix, a quick fix mutates source code**
7. **Statistics service records the violation for the dashboard**

This creates a closed loop: detection → presentation → correction → aggregate reporting.

###### Architectural boundary: “analysis vs. UI”

A useful diagram boundary is to separate:

- **Rule evaluation and violation generation**
- **IDE presentation and user interaction**
- **Fix application and statistics aggregation**

That separation is visible in the module layout and helps explain how the plugin stays extensible: rules are independent of how findings are shown.

---

##### 2) Android demo app: `app/`

This is a conventional Android application module, not the plugin itself.

###### Purpose
It serves as a showcase/demo environment for ComposeGuard rules. The source tree contains multiple Compose demos:

- `AllRulesDemo.kt`
- `ComposableRulesDemo.kt`
- `ModifierRulesDemo.kt`
- `NamingRulesDemo.kt`
- `ParameterRulesDemo.kt`
- `StateRulesDemo.kt`

These files provide concrete code patterns that trigger the plugin’s inspections. The app’s main entry point is `sample/MainActivity.kt`, with a Compose theme under `sample/ui/theme/`.

###### Role in the architecture
This module is best viewed as an **example consumer** of the plugin’s analysis capabilities. It is not part of the plugin runtime, but it provides realistic Compose source for manual validation and screenshots.

---

##### 3) Sample sources: `sample/`

The `sample/ComposeGuardTestSample.kt` file is a test fixture-style source sample. It likely holds intentionally structured code that exercises many rules at once, supporting automated tests and rule metadata validation.

This is distinct from the Android app:
- `app/` is a runnable UI demo
- `sample/` is a source fixture for tests and rule verification

---

##### Rule taxonomy and behavior

The rule set is the heart of the repository. The README and file layout show these rule groups:

- **Naming**
  - composable naming
  - modifier naming
  - CompositionLocal naming
  - preview and multipreview naming
  - event callback naming

- **Modifiers**
  - required modifier parameters
  - default modifier values
  - modifier ordering
  - modifier reuse and top-most placement
  - avoid `composed {}`

- **State**
  - remember state
  - use type-specific mutable state
  - hoist state
  - avoid mutable state as parameter

- **Parameters**
  - parameter ordering
  - trailing lambda conventions
  - explicit dependencies
  - mutable type parameters
  - ViewModel forwarding

- **Composables**
  - content emission
  - multiple content slots
  - effect keys
  - movable content
  - preview visibility

- **Stricter**
  - Material 2 usage detection
  - unstable collections detection

- **Experimental / performance**
  - lazy list key/contentType rules
  - derived state candidate detection
  - lifecycle-aware collection
  - defer state reads

A good diagram would depict these as rule families feeding into the same detection pipeline, rather than as separate subsystems.

---

##### Quick fixes as a parallel output path

Each rule can optionally expose a matching quick fix. The quick fixes are not generic utilities; they are strongly tied to rule findings and implement specific refactor actions. This creates a direct mapping:

- violation detected by rule
- quick fix offered by IDE
- source code updated in place

That pairing is an important architectural feature because the plugin is not just diagnostic; it is corrective.

---

##### Configuration and suppression model

The plugin includes two important control planes:

- **Global and per-category settings**
  - enable/disable the plugin
  - toggle gutter icons and inlay hints
  - enable/disable rule categories and individual rules
  - optionally enable experimental rules

- **Inline suppression**
  - specific rule suppressions are supported in source code

These form the main boundaries for controlling signal/noise in existing codebases.

---

##### Test architecture

The `src/test` tree is extensive and mirrors the rule structure closely. Tests are organized by feature area:

- rule registry and rule metadata tests
- per-category rule tests
- quick fix tests
- settings state tests

This indicates a highly modular architecture where each rule is expected to be independently testable, and each quick fix is expected to be tied to a corresponding rule scenario.

The test layout also suggests a strong emphasis on:
- rule completeness
- metadata correctness
- quick-fix behavior
- category grouping integrity

---

##### CI and build tooling

Relevant infrastructure that affects the architecture:

- **Gradle Kotlin DSL** at the root and module level
- **GitHub Actions**
  - `android.yml` for Android/sample module work
  - `intellij-plugin.yml` for plugin validation/building
- **IntelliJ run configurations** under `.run/`
- **Spotless** formatting configuration
- **Version catalog** in `gradle/libs.versions.toml`

These don’t change runtime behavior, but they define how the plugin and sample app are built, tested, and packaged.

---

##### How to draw the architecture diagram

A clear diagram for this repository should show:

- **Kotlin source code in an IDE**
  - flowing into **ComposeGuard plugin analysis**
- **Rule registry**
  - feeding multiple rule families
- **Findings**
  - flowing outward to:
    - editor highlights/annotations
    - gutter markers
    - inline hints
    - tooltips
    - statistics dashboard
    - quick fixes
- **Settings**
  - controlling which rules and UI surfaces are active
- **Sample Android app**
  - acting as a consumer/demo source target
- **Tests**
  - validating rules, fixes, and settings independently

The key architectural idea is that ComposeGuard is an IDE-native static analysis and remediation system for Jetpack Compose, with a modular rule engine and multiple presentation channels layered on top of the same violation model.

Main entry points: [`compose-guard/src/main/kotlin/io/androidpoet/composeguard/rules/ComposeRuleRegistry.kt`](https://github.com/androidpoet/compose-guard/blob/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/rules/ComposeRuleRegistry.kt) (Rule registry), [`compose-guard/src/main/kotlin/io/androidpoet/composeguard/settings`](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/settings) (Settings), [`compose-guard/src/test/kotlin/io/androidpoet/composeguard`](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/test/kotlin/io/androidpoet/composeguard) (Rule tests), [`build.gradle.kts`](https://github.com/androidpoet/compose-guard/blob/HEAD/build.gradle.kts) (Gradle build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Build & CI"
  root_build["Gradle build<br/>[build.gradle.kts]"]
  ci["CI workflows<br/>automation<br/>[workflows]"]
  docs["Docs<br/>documentation<br/>[README.md]"]
end

subgraph "ComposeGuard Plugin"
  plugin_entry["Plugin entry<br/>intellij plugin<br/>[plugin.xml]"]
  rule_registry[("Rule registry<br/>core rules")]
  rules_ui["Analysis surfaces<br/>IDE integration"]
  rule_families["Rule families<br/>Compose rules"]
  quickfix["Quick fixes<br/>source actions"]
  settings["Settings<br/>configuration"]
  stats[("Statistics<br/>aggregation")]
  toolwindow["Dashboard<br/>IDE tool window"]
end

subgraph "Demo App"
  demo_app["Android app<br/>sample app"]
  demo_screens["Demo screens<br/>compose samples<br/>[AllRulesDemo.kt]"]
  demo_activity["Main activity<br/>android entry<br/>[MainActivity.kt]"]
  theme["Theme<br/>[Theme.kt]"]
end

subgraph "Samples & Tests"
  plugin_tests["Rule tests<br/>test suite"]
  sample_fixture["Test sample<br/>fixture source"]
end

root_build -->|"builds"| plugin_entry
root_build -->|"builds"| demo_app
ci -->|"validates"| root_build
plugin_entry -->|"loads"| rule_registry
rule_registry -->|"organizes"| rule_families
rule_registry -->|"feeds"| rules_ui
rules_ui -->|"offers fixes"| quickfix
settings -->|"filters"| rule_registry
settings -->|"controls"| rules_ui
settings -->|"controls"| stats
rules_ui -->|"records"| stats
stats -->|"displays"| toolwindow
demo_activity -->|"hosts"| demo_screens
demo_app -->|"uses"| theme
demo_screens -.->|"triggers"| rule_registry
sample_fixture -->|"backs"| plugin_tests
plugin_tests -->|"verifies"| rule_registry
plugin_tests -->|"verifies"| quickfix
docs -.->|"describes"| rule_registry

click root_build "https://github.com/androidpoet/compose-guard/blob/master/build.gradle.kts"
click ci "https://github.com/androidpoet/compose-guard/blob/master/.github/workflows"
click plugin_entry "https://github.com/androidpoet/compose-guard/blob/master/compose-guard/src/main/resources/META-INF/plugin.xml"
click rule_registry "https://github.com/androidpoet/compose-guard/blob/master/compose-guard/src/main/kotlin/io/androidpoet/composeguard/rules/ComposeRuleRegistry.kt"
click quickfix "https://github.com/androidpoet/compose-guard/tree/master/compose-guard/src/main/kotlin/io/androidpoet/composeguard/quickfix"
click settings "https://github.com/androidpoet/compose-guard/tree/master/compose-guard/src/main/kotlin/io/androidpoet/composeguard/settings"
click stats "https://github.com/androidpoet/compose-guard/tree/master/compose-guard/src/main/kotlin/io/androidpoet/composeguard/statistics"
click toolwindow "https://github.com/androidpoet/compose-guard/tree/master/compose-guard/src/main/kotlin/io/androidpoet/composeguard/toolwindow"
click plugin_tests "https://github.com/androidpoet/compose-guard/tree/master/compose-guard/src/test/kotlin/io/androidpoet/composeguard"
click demo_app "https://github.com/androidpoet/compose-guard/tree/master/app/src/main/kotlin/io/androidpoet/composeguard/sample"
click demo_screens "https://github.com/androidpoet/compose-guard/blob/master/app/src/main/kotlin/io/androidpoet/composeguard/sample/AllRulesDemo.kt"
click demo_activity "https://github.com/androidpoet/compose-guard/blob/master/app/src/main/kotlin/io/androidpoet/composeguard/sample/MainActivity.kt"
click sample_fixture "https://github.com/androidpoet/compose-guard/blob/master/sample/ComposeGuardTestSample.kt"
click theme "https://github.com/androidpoet/compose-guard/blob/master/app/src/main/kotlin/io/androidpoet/composeguard/sample/ui/theme/Theme.kt"
click docs "https://github.com/androidpoet/compose-guard/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class root_build,ci,docs toneBlue
class plugin_entry,rule_registry,rules_ui,rule_families,quickfix,settings,stats,toolwindow toneAmber
class demo_app,demo_screens,demo_activity,theme toneMint
class plugin_tests,sample_fixture toneRose
```

## Components

### Build & CI

Root build, formatting, and workflow automation.

- [Gradle build](https://github.com/androidpoet/compose-guard/blob/HEAD/build.gradle.kts): build · Root Gradle and dependency/version management for the multi-module repo. · `build.gradle.kts`
- [CI workflows](https://github.com/androidpoet/compose-guard/blob/HEAD/.github/workflows): automation · GitHub Actions and repository automation for Android and plugin validation. · `.github/workflows`
- [Docs](https://github.com/androidpoet/compose-guard/blob/HEAD/README.md): documentation · Repository documentation, changelog, release notes, and rule catalog. · `README.md`

### ComposeGuard Plugin

The IntelliJ Platform plugin and its analysis pipeline.

- [Plugin entry](https://github.com/androidpoet/compose-guard/blob/HEAD/compose-guard/src/main/resources/META-INF/plugin.xml): intellij plugin · IntelliJ Platform plugin descriptor and packaging boundary. · `compose-guard/src/main/resources/META-INF/plugin.xml`
- [Rule registry](https://github.com/androidpoet/compose-guard/blob/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/rules/ComposeRuleRegistry.kt): core rules · Central catalog of ComposeGuard rules and shared rule model. · `compose-guard/src/main/kotlin/io/androidpoet/composeguard/rules/ComposeRuleRegistry.kt`
- **Analysis surfaces**: IDE integration · IDE inspection, annotator, inlay, and line-marker integrations that render findings.
- **Rule families**: Compose rules · Grouped rule categories for naming, modifiers, parameters, composables, state, and stricter/performance checks.
- [Quick fixes](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/quickfix): source actions · Code actions that remediate rule violations in place. · `compose-guard/src/main/kotlin/io/androidpoet/composeguard/quickfix`
- [Settings](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/settings): configuration · Global, per-category, and per-rule controls plus experimental rule toggles. · `compose-guard/src/main/kotlin/io/androidpoet/composeguard/settings`
- [Statistics](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/statistics): aggregation · Violation counting and project-level statistics collection. · `compose-guard/src/main/kotlin/io/androidpoet/composeguard/statistics`
- [Dashboard](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/main/kotlin/io/androidpoet/composeguard/toolwindow): IDE tool window · ComposeGuard statistics panel shown inside the IDE. · `compose-guard/src/main/kotlin/io/androidpoet/composeguard/toolwindow`

### Demo App

Runnable Android sample used to showcase plugin findings.

- [Android app](https://github.com/androidpoet/compose-guard/tree/HEAD/app/src/main/kotlin/io/androidpoet/composeguard/sample): sample app · Runnable Compose demo application that showcases rule violations. · `app/src/main/kotlin/io/androidpoet/composeguard/sample`
- [Demo screens](https://github.com/androidpoet/compose-guard/blob/HEAD/app/src/main/kotlin/io/androidpoet/composeguard/sample/AllRulesDemo.kt): compose samples · Sample Compose screens that intentionally exercise rule categories. · `app/src/main/kotlin/io/androidpoet/composeguard/sample/AllRulesDemo.kt`
- [Main activity](https://github.com/androidpoet/compose-guard/blob/HEAD/app/src/main/kotlin/io/androidpoet/composeguard/sample/MainActivity.kt): android entry · Android entry point hosting the demo Compose content. · `app/src/main/kotlin/io/androidpoet/composeguard/sample/MainActivity.kt`
- [Theme](https://github.com/androidpoet/compose-guard/blob/HEAD/app/src/main/kotlin/io/androidpoet/composeguard/sample/ui/theme/Theme.kt): ui theme · Compose theme used by the demo application. · `app/src/main/kotlin/io/androidpoet/composeguard/sample/ui/theme/Theme.kt`

### Samples & Tests

Source fixtures and test coverage for rules, fixes, and settings.

- [Rule tests](https://github.com/androidpoet/compose-guard/tree/HEAD/compose-guard/src/test/kotlin/io/androidpoet/composeguard): test suite · Tests covering rules, metadata, quick fixes, and settings behavior. · `compose-guard/src/test/kotlin/io/androidpoet/composeguard`
- [Test sample](https://github.com/androidpoet/compose-guard/blob/HEAD/sample/ComposeGuardTestSample.kt): fixture source · Standalone source fixture used for rule verification and demonstrations. · `sample/ComposeGuardTestSample.kt`

## Connections

- Gradle build → Plugin entry: builds · Root build config assembles the plugin module.
- Gradle build → Android app: builds · Root build config includes the Android demo module.
- CI workflows → Gradle build: validates · Workflows run build and verification tasks.
- Plugin entry → Rule registry: loads · The plugin descriptor anchors the runtime plugin components.
- Rule registry → Rule families: organizes · Registry groups the supported rule families.
- Rule registry → Analysis surfaces: feeds · Detected rules are consumed by IDE presentation layers.
- Analysis surfaces → Quick fixes: offers fixes · UI findings expose matching remediation actions.
- Settings → Rule registry: filters · Rule and category toggles constrain which rules participate.
- Settings → Analysis surfaces: controls · Settings govern editor affordances like highlighting and hints.
- Settings → Statistics: controls · Statistics and dashboard behavior are influenced by configuration.
- Analysis surfaces → Statistics: records · Findings are aggregated into violation statistics.
- Statistics → Dashboard: displays · Aggregated statistics are rendered in the dashboard tool window.
- Main activity → Demo screens: hosts · The activity hosts the sample Compose screens.
- Android app → Theme: uses · The app applies a shared Compose theme.
- Demo screens → Rule registry: triggers · Demo code is designed to activate ComposeGuard rules.
- Test sample → Rule tests: backs · Fixture source underpins automated rule and quick-fix tests.
- Rule tests → Rule registry: verifies · Tests validate rule metadata and detection behavior.
- Rule tests → Quick fixes: verifies · Tests validate source actions and remediation logic.
- Docs → Rule registry: describes · Documentation explains the rule catalog and plugin behavior.
