# anonymoose725/pylon architecture

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

- Interactive diagram: https://gitdiagram.com/anonymoose725/pylon
- Repository: https://github.com/anonymoose725/pylon
- Video tour (about a minute): https://gitdiagram.com/anonymoose725/pylon/video

## Overview

Pylon is a Python static-analysis CLI. Its main workflow discovers Python files, runs registered AST-based rules, and prints findings; with `--explain`, it adds surrounding source context and asks a selected LLM provider for a judgment. The graph preserves the implemented rule set and provider integrations documented in the README. Evidence is strongest for the CLI, several rules, and Ollama; some provider and rule implementations were not excerpted, so uncertain internal dispatch details are omitted.

Main entry points: [`src/pylon_analyzer/rules/registry.py`](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/registry.py) (Rule registry), [`src/pylon_analyzer/cli.py`](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/cli.py) (File scan and report), [`src/pylon_analyzer/ai/explain.py`](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/explain.py) (Finding explanation), [`src/pylon_analyzer/ai/providers/ollama_provider.py`](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/providers/ollama_provider.py) (Ollama provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["File scan and report<br/>[cli.py]"]
end

subgraph group_rules["Static rules"]
  node_registry["Rule registry<br/>[registry.py]"]
  node_bare["Bare excepts<br/>[bare_excepts.py]"]
  node_unused["Unused imports<br/>[unused_imports.py]"]
  node_mutable["Mutable defaults"]
  node_wildcard["Wildcard imports"]
  node_compare["Constant comparisons"]
  node_shadowfunc["Shadowed definitions"]
  node_shadowbuiltin["Shadowed builtins"]
end

subgraph group_findings["Finding model"]
  node_finding["Finding schema<br/>[base.py]"]
end

subgraph group_llm["LLM explanations"]
  node_explain["Finding explanation<br/>[explain.py]"]
  node_providerbase["Provider interface<br/>[base.py]"]
  node_ollama["Ollama provider<br/>[ollama_provider.py]"]
  node_providers["Other providers"]
end

node_user(("CLI user"))
node_ollamaservice{{"Ollama service"}}
node_llmservices{{"Hosted LLM services"}}

node_user -->|"runs"| node_cli
node_cli -->|"loads rules"| node_registry
node_registry -->|"registers"| node_bare
node_registry -->|"registers"| node_unused
node_registry -->|"registers"| node_mutable
node_registry -->|"registers"| node_wildcard
node_registry -->|"registers"| node_compare
node_registry -->|"registers"| node_shadowfunc
node_registry -->|"registers"| node_shadowbuiltin
node_cli -->|"collects findings"| node_finding
node_cli -->|"requests explanation"| node_explain
node_explain -->|"calls completion"| node_providerbase
node_cli -.->|"selects provider"| node_ollama
node_cli -.->|"selects provider"| node_providers
node_ollama -->|"sends prompt"| node_ollamaservice
node_providers -.->|"sends prompts"| node_llmservices

click node_cli "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/cli.py"
click node_registry "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/registry.py"
click node_bare "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/bare_excepts.py"
click node_unused "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/unused_imports.py"
click node_mutable "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/mutable_default_args.py"
click node_wildcard "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/wildcard_imports.py"
click node_compare "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/improper_compare_keyword_const.py"
click node_shadowfunc "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/shadowed_functions.py"
click node_shadowbuiltin "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/shadowed_builtins.py"
click node_finding "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/base.py"
click node_explain "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/explain.py"
click node_providerbase "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/providers/base.py"
click node_ollama "https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/providers/ollama_provider.py"
click node_providers "https://github.com/anonymoose725/pylon/tree/main/src/pylon_analyzer/ai/providers"

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_registry,node_bare,node_unused,node_mutable,node_wildcard,node_compare,node_shadowfunc,node_shadowbuiltin toneAmber
class node_finding toneMint
class node_explain,node_providerbase,node_ollama,node_providers toneRose
class node_ollamaservice,node_llmservices toneIndigo
```

## Components

### CLI workflow

- [File scan and report](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/cli.py): `src/pylon_analyzer/cli.py`

### Static rules

- [Rule registry](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/registry.py): `src/pylon_analyzer/rules/registry.py`
- [Bare excepts](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/bare_excepts.py): `src/pylon_analyzer/rules/bare_excepts.py`
- [Unused imports](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/unused_imports.py): `src/pylon_analyzer/rules/unused_imports.py`
- [Mutable defaults](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/mutable_default_args.py): `src/pylon_analyzer/rules/mutable_default_args.py`
- [Wildcard imports](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/wildcard_imports.py): `src/pylon_analyzer/rules/wildcard_imports.py`
- [Constant comparisons](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/improper_compare_keyword_const.py): `src/pylon_analyzer/rules/improper_compare_keyword_const.py`
- [Shadowed definitions](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/shadowed_functions.py): `src/pylon_analyzer/rules/shadowed_functions.py`
- [Shadowed builtins](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/shadowed_builtins.py): `src/pylon_analyzer/rules/shadowed_builtins.py`

### Finding model

- [Finding schema](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/rules/base.py): `src/pylon_analyzer/rules/base.py`

### LLM explanations

- [Finding explanation](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/explain.py): `src/pylon_analyzer/ai/explain.py`
- [Provider interface](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/providers/base.py): `src/pylon_analyzer/ai/providers/base.py`
- [Ollama provider](https://github.com/anonymoose725/pylon/blob/main/src/pylon_analyzer/ai/providers/ollama_provider.py): `src/pylon_analyzer/ai/providers/ollama_provider.py`
- [Other providers](https://github.com/anonymoose725/pylon/tree/main/src/pylon_analyzer/ai/providers): `src/pylon_analyzer/ai/providers`

### Other components

- **CLI user**
- **Ollama service**
- **Hosted LLM services**

## Connections

- CLI user → File scan and report: runs (evidence: `src/pylon_analyzer/cli.py`)
- File scan and report → Rule registry: loads rules (evidence: `src/pylon_analyzer/cli.py`)
- Rule registry → Bare excepts: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- Rule registry → Unused imports: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- Rule registry → Mutable defaults: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- Rule registry → Wildcard imports: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- Rule registry → Constant comparisons: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- Rule registry → Shadowed definitions: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- Rule registry → Shadowed builtins: registers (evidence: `src/pylon_analyzer/rules/registry.py`)
- File scan and report → Finding schema: collects findings (evidence: `src/pylon_analyzer/cli.py`)
- File scan and report → Finding explanation: requests explanation (evidence: `src/pylon_analyzer/cli.py`)
- Finding explanation → Provider interface: calls completion (evidence: `src/pylon_analyzer/ai/explain.py`)
- File scan and report → Ollama provider: selects provider
- File scan and report → Other providers: selects provider (evidence: `src/pylon_analyzer/cli.py`)
- Ollama provider → Ollama service: sends prompt (evidence: `src/pylon_analyzer/ai/providers/ollama_provider.py`)
- Other providers → Hosted LLM services: sends prompts (evidence: `README.md`)