# kds1123001/clarity architecture

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

- Interactive diagram: https://gitdiagram.com/kds1123001/clarity
- Repository: https://github.com/kds1123001/clarity

## Overview

Clarity is a command-line diagnostic explainer: users pipe compiler output into it or ask it to run a command, then receive located diagnostics and actionable guidance. The README documents parsing, rule matching, identifier suggestions, and rendering; sampled source confirms the CLI’s calls into parsing and reporting. The tree does not include the documented internal parser, report, or suggestion implementations, so those links are limited to documented behavior and unsupported source paths are left null.

Main entry points: [`main.go`](https://github.com/kds1123001/clarity/blob/main/main.go) (CLI modes), [`suggest.go`](https://github.com/kds1123001/clarity/blob/main/suggest.go) (Diagnostic parser), [`data.json`](https://github.com/kds1123001/clarity/blob/main/data.json) (Rule database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["CLI modes<br/>[main.go]"]
end

subgraph group_diagnostics["Diagnostic processing"]
  node_parser["Diagnostic parser<br/>[suggest.go]"]
  node_python["Python traceback parser<br/>[suggest.go]"]
  node_generic["Generic error parser<br/>[suggest.go]"]
  node_language["Language detection<br/>[suggest.go]"]
end

subgraph group_guidance["Explanation and output"]
  node_rules["Rule database<br/>[data.json]"]
  node_matcher["Rule matching"]
  node_suggestions["Identifier suggestions"]
  node_report["Diagnostic renderer"]
  node_output["Explained diagnostics"]
end

node_user(("User"))
node_compiler["Compiler or interpreter"]

node_user -->|"pipes output"| node_cli
node_user -->|"starts run"| node_cli
node_cli -->|"executes command"| node_compiler
node_compiler -->|"returns output"| node_cli
node_cli -->|"detects language"| node_language
node_cli -->|"parses output"| node_parser
node_parser -->|"dispatches traceback"| node_python
node_parser -->|"parses fallback"| node_generic
node_cli -->|"prints diagnostics"| node_report
node_matcher -->|"matches patterns"| node_rules
node_parser -->|"matches messages"| node_matcher
node_parser -->|"suggests identifiers"| node_suggestions
node_report -->|"renders guidance"| node_output
node_output -->|"displays results"| node_user

click node_cli "https://github.com/kds1123001/clarity/blob/main/main.go"
click node_parser "https://github.com/kds1123001/clarity/blob/main/suggest.go"
click node_python "https://github.com/kds1123001/clarity/blob/main/suggest.go"
click node_generic "https://github.com/kds1123001/clarity/blob/main/suggest.go"
click node_language "https://github.com/kds1123001/clarity/blob/main/suggest.go"
click node_rules "https://github.com/kds1123001/clarity/blob/main/data.json"

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 node_cli,node_user toneBlue
class node_parser,node_python,node_generic,node_language toneAmber
class node_rules,node_matcher,node_suggestions,node_report,node_output toneMint
class node_compiler toneIndigo
```

## Components

### CLI entry

- [CLI modes](https://github.com/kds1123001/clarity/blob/main/main.go): `main.go`

### Diagnostic processing

- [Diagnostic parser](https://github.com/kds1123001/clarity/blob/main/suggest.go): `suggest.go`
- [Python traceback parser](https://github.com/kds1123001/clarity/blob/main/suggest.go): `suggest.go`
- [Generic error parser](https://github.com/kds1123001/clarity/blob/main/suggest.go): `suggest.go`
- [Language detection](https://github.com/kds1123001/clarity/blob/main/suggest.go): `suggest.go`

### Explanation and output

- [Rule database](https://github.com/kds1123001/clarity/blob/main/data.json): `data.json`
- **Rule matching**
- **Identifier suggestions**
- **Diagnostic renderer**
- **Explained diagnostics**

### Other components

- **User**
- **Compiler or interpreter**

## Connections

- User → CLI modes: pipes output
- User → CLI modes: starts run
- CLI modes → Compiler or interpreter: executes command
- Compiler or interpreter → CLI modes: returns output
- CLI modes → Language detection: detects language
- CLI modes → Diagnostic parser: parses output
- Diagnostic parser → Python traceback parser: dispatches traceback
- Diagnostic parser → Generic error parser: parses fallback
- CLI modes → Diagnostic renderer: prints diagnostics
- Rule matching → Rule database: matches patterns
- Diagnostic parser → Rule matching: matches messages
- Diagnostic parser → Identifier suggestions: suggests identifiers
- Diagnostic renderer → Explained diagnostics: renders guidance
- Explained diagnostics → User: displays results