# ibrahimmian36/leanscreen architecture

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

- Interactive diagram: https://gitdiagram.com/ibrahimmian36/leanscreen
- Repository: https://github.com/ibrahimmian36/leanscreen

## Overview

leanscreen screens informal/Lean statement pairs through a reject-only workflow: deterministic lints and vacuity checks, optional Lean elaboration, then (in deep mode) two independent LLM reviews and an adversarial probe. The score is returned through either the one-shot CLI or MCP; file input is paired with Lean doc comments. The graph also preserves the documented Claude plugin/skill capability. Source excerpts show the scoring and service boundaries, but not every runtime construction detail, so uncertain wiring is omitted.

Main entry points: [`src/leanscreen/score.py`](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/score.py) (Pair scorer), [`src/leanscreen/cli.py`](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/cli.py) (Check CLI), [`src/leanscreen/server.py`](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/server.py) (MCP service), [`src/leanscreen/llm.py`](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/llm.py) (Anthropic client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entrypoints"]
  node_cli["Check CLI<br/>[cli.py]"]
  node_mcp["MCP service<br/>[server.py]"]
  node_leanfile["Lean file pairing<br/>[leanfile.py]"]
  node_plugin["Claude skill<br/>[SKILL.md]"]
end

subgraph group_screen["Screening pipeline"]
  node_score["Pair scorer<br/>[score.py]"]
  node_lints["Structural lints<br/>[lints.py]"]
  node_quality["Vacuity checks<br/>[quality.py]"]
  node_backtranslate["Back-translation judge<br/>[backtranslate.py]"]
  node_falsify["Counterexample probe<br/>[falsify.py]"]
end

subgraph group_integrations["External checks"]
  node_verifier["Lean verification<br/>[verify.py]"]
  node_repl["Persistent Lean REPL<br/>[lean_server.py]"]
  node_llm["Anthropic client<br/>[llm.py]"]
  node_anthropic["Anthropic API"]
  node_lean["Lean / mathlib"]
end

subgraph group_support["Runtime support"]
  node_config["Settings<br/>[config.py]"]
  node_errors["Typed errors<br/>[errors.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
end

node_user(("Author / client"))

node_user -->|"runs check"| node_cli
node_user -->|"calls tools"| node_mcp
node_user -->|"invokes skill"| node_plugin
node_plugin -->|"uses tools"| node_mcp
node_cli -->|"pairs declarations"| node_leanfile
node_cli -->|"starts runtime"| node_mcp
node_mcp -->|"scores pairs"| node_score
node_cli -->|"scores pairs"| node_score
node_score -->|"runs lints"| node_lints
node_score -->|"checks vacuity"| node_quality
node_score -->|"verifies Lean"| node_verifier
node_score -->|"requests review"| node_backtranslate
node_score -->|"probes counterexample"| node_falsify
node_score -->|"uses judges"| node_llm
node_lints -->|"reuses checks"| node_quality
node_backtranslate -->|"submits prompts"| node_llm
node_falsify -->|"submits probe"| node_llm
node_llm -->|"sends requests"| node_anthropic
node_repl -->|"checks statements"| node_lean
node_verifier -->|"elaborates statements"| node_lean
node_mcp -->|"warms verifier"| node_repl
node_mcp -->|"loads settings"| node_config
node_cli -->|"loads settings"| node_config
node_llm -->|"raises failures"| node_errors
node_llm -->|"records usage"| node_logging
node_cli -->|"configures logs"| node_logging
node_verifier -->|"raises failures"| node_errors

click node_cli "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/cli.py"
click node_mcp "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/server.py"
click node_leanfile "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/leanfile.py"
click node_plugin "https://github.com/ibrahimmian36/leanscreen/blob/main/skills/screen/SKILL.md"
click node_score "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/score.py"
click node_lints "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/lints.py"
click node_quality "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/quality.py"
click node_backtranslate "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/backtranslate.py"
click node_falsify "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/falsify.py"
click node_verifier "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/verify.py"
click node_repl "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/lean_server.py"
click node_llm "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/llm.py"
click node_config "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/config.py"
click node_errors "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/errors.py"
click node_logging "https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/logging.py"

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_mcp,node_leanfile,node_plugin,node_user toneBlue
class node_score,node_lints,node_quality,node_backtranslate,node_falsify toneAmber
class node_verifier,node_repl,node_llm,node_anthropic,node_lean toneMint
class node_config,node_errors,node_logging toneRose
```

## Components

### User entrypoints

- [Check CLI](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/cli.py): `src/leanscreen/cli.py`
- [MCP service](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/server.py): `src/leanscreen/server.py`
- [Lean file pairing](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/leanfile.py): `src/leanscreen/leanfile.py`
- [Claude skill](https://github.com/ibrahimmian36/leanscreen/blob/main/skills/screen/SKILL.md): `skills/screen/SKILL.md`

### Screening pipeline

- [Pair scorer](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/score.py): `src/leanscreen/score.py`
- [Structural lints](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/lints.py): `src/leanscreen/lints.py`
- [Vacuity checks](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/quality.py): `src/leanscreen/quality.py`
- [Back-translation judge](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/backtranslate.py): `src/leanscreen/backtranslate.py`
- [Counterexample probe](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/falsify.py): `src/leanscreen/falsify.py`

### External checks

- [Lean verification](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/verify.py): `src/leanscreen/verify.py`
- [Persistent Lean REPL](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/lean_server.py): `src/leanscreen/lean_server.py`
- [Anthropic client](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/llm.py): `src/leanscreen/llm.py`
- **Anthropic API**
- **Lean / mathlib**

### Runtime support

- [Settings](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/config.py): `src/leanscreen/config.py`
- [Typed errors](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/errors.py): `src/leanscreen/errors.py`
- [Structured logging](https://github.com/ibrahimmian36/leanscreen/blob/main/src/leanscreen/logging.py): `src/leanscreen/logging.py`

### Other components

- **Author / client**

## Connections

- Author / client → Check CLI: runs check (evidence: `README.md`)
- Author / client → MCP service: calls tools (evidence: `README.md`)
- Author / client → Claude skill: invokes skill (evidence: `README.md`)
- Claude skill → MCP service: uses tools (evidence: `README.md`)
- Check CLI → Lean file pairing: pairs declarations (evidence: `src/leanscreen/cli.py`)
- Check CLI → MCP service: starts runtime (evidence: `src/leanscreen/server.py`)
- MCP service → Pair scorer: scores pairs (evidence: `src/leanscreen/server.py`)
- Check CLI → Pair scorer: scores pairs (evidence: `src/leanscreen/cli.py`)
- Pair scorer → Structural lints: runs lints (evidence: `src/leanscreen/score.py`)
- Pair scorer → Vacuity checks: checks vacuity (evidence: `src/leanscreen/score.py`)
- Pair scorer → Lean verification: verifies Lean (evidence: `src/leanscreen/score.py`)
- Pair scorer → Back-translation judge: requests review (evidence: `src/leanscreen/score.py`)
- Pair scorer → Counterexample probe: probes counterexample (evidence: `src/leanscreen/score.py`)
- Pair scorer → Anthropic client: uses judges (evidence: `src/leanscreen/score.py`)
- Structural lints → Vacuity checks: reuses checks (evidence: `src/leanscreen/lints.py`)
- Back-translation judge → Anthropic client: submits prompts (evidence: `src/leanscreen/backtranslate.py`)
- Counterexample probe → Anthropic client: submits probe (evidence: `src/leanscreen/falsify.py`)
- Anthropic client → Anthropic API: sends requests (evidence: `src/leanscreen/llm.py`)
- Persistent Lean REPL → Lean / mathlib: checks statements (evidence: `src/leanscreen/lean_server.py`)
- Lean verification → Lean / mathlib: elaborates statements (evidence: `README.md`)
- MCP service → Persistent Lean REPL: warms verifier (evidence: `src/leanscreen/server.py`)
- MCP service → Settings: loads settings (evidence: `src/leanscreen/server.py`)
- Check CLI → Settings: loads settings (evidence: `src/leanscreen/cli.py`)
- Anthropic client → Typed errors: raises failures (evidence: `src/leanscreen/llm.py`)
- Anthropic client → Structured logging: records usage (evidence: `src/leanscreen/llm.py`)
- Check CLI → Structured logging: configures logs (evidence: `src/leanscreen/cli.py`)
- Lean verification → Typed errors: raises failures (evidence: `src/leanscreen/lean_server.py`)
