# liustack/modlens architecture

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

- Interactive diagram: https://gitdiagram.com/liustack/modlens
- Repository: https://github.com/liustack/modlens

## Overview

ModLens is a vision plugin and CLI that turns pasted or referenced images into structured evidence and answers for text-only models. In DSH, the browser plugin captures pasted image bytes, the host side stores them as a private temporary file, and the CLI analyzes that image; alternatively, users can invoke the CLI directly with an image path or URL. The analyzer selects providers and fails over across built-in engines and reusable local CLIs. Auto-discovered routes, paste recovery, model guarding, and configuration/health commands are distinct supporting capabilities. Source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/main.ts`](https://github.com/liustack/modlens/blob/main/src/main.ts) (ModLens CLI), [`src/analyzer.ts`](https://github.com/liustack/modlens/blob/main/src/analyzer.ts) (Image analyzer), [`src/providers`](https://github.com/liustack/modlens/tree/main/src/providers) (Provider implementations), [`src/providers/index.ts`](https://github.com/liustack/modlens/blob/main/src/providers/index.ts) (Provider registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Image intake"]
  node_pasteclient["Paste listener<br/>[client.js]"]
  node_pasteplugin["Paste and tool routes<br/>[index.js]"]
  node_recovery["Paste recovery<br/>[index.ts]"]
end

subgraph group_analysis["Vision analysis"]
  node_cli["ModLens CLI<br/>[main.ts]"]
  node_analyzer["Image analyzer<br/>[analyzer.ts]"]
  node_prompt["Evidence prompt<br/>[prompt.ts]"]
end

subgraph group_engines["Vision engines"]
  node_autodiscover["Route discovery<br/>[discover.ts]"]
  node_autoroutes["Borrowed routes<br/>[routes.ts]"]
  node_providerregistry["Provider registry<br/>[index.ts]"]
  node_providerimpl["Provider implementations"]
end

subgraph group_support["Safety and setup"]
  node_config[("Configuration<br/>[config.ts]")]
  node_guard["Model guard<br/>[index.ts]"]
  node_network["Remote image safety<br/>[network.ts]"]
  node_doctor["Health diagnostics<br/>[doctor.ts]"]
  node_cooldown["Failover cooldown<br/>[cooldown.ts]"]
end

node_user(("User"))
node_dsh["DSH host"]
node_harnessdata[("Harness session stores")]
node_visionservices["Vision APIs"]
node_localclis["Local vision CLIs"]

node_user -->|"pastes image"| node_pasteclient
node_pasteclient -->|"uploads bytes"| node_pasteplugin
node_pasteplugin -->|"stores path"| node_dsh
node_dsh -->|"invokes read"| node_cli
node_user -->|"requests image read"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"checks model"| node_guard
node_cli -->|"builds cooldown"| node_cooldown
node_cli -->|"analyzes image"| node_analyzer
node_analyzer -->|"builds prompt"| node_prompt
node_analyzer -->|"selects and runs"| node_providerregistry
node_providerregistry -->|"dispatches provider"| node_providerimpl
node_providerimpl -->|"sends image request"| node_visionservices
node_providerimpl -.->|"spawns vision CLI"| node_localclis
node_analyzer -->|"validates remote image"| node_network
node_autodiscover -->|"supplies routes"| node_autoroutes
node_autoroutes -->|"adds providers"| node_providerregistry
node_user -->|"requests recovered paste"| node_recovery
node_recovery -->|"reads image records"| node_harnessdata
node_cli -->|"builds report"| node_doctor
node_doctor -->|"reads settings"| node_config

click node_cli "https://github.com/liustack/modlens/blob/main/src/main.ts"
click node_analyzer "https://github.com/liustack/modlens/blob/main/src/analyzer.ts"
click node_prompt "https://github.com/liustack/modlens/blob/main/src/prompt.ts"
click node_pasteclient "https://github.com/liustack/modlens/blob/main/dsh/client.js"
click node_pasteplugin "https://github.com/liustack/modlens/blob/main/dsh/index.js"
click node_recovery "https://github.com/liustack/modlens/blob/main/src/recoverPaste/index.ts"
click node_autodiscover "https://github.com/liustack/modlens/blob/main/src/auto/discover.ts"
click node_autoroutes "https://github.com/liustack/modlens/blob/main/src/auto/routes.ts"
click node_providerregistry "https://github.com/liustack/modlens/blob/main/src/providers/index.ts"
click node_providerimpl "https://github.com/liustack/modlens/tree/main/src/providers"
click node_config "https://github.com/liustack/modlens/blob/main/src/config.ts"
click node_guard "https://github.com/liustack/modlens/blob/main/src/guard/index.ts"
click node_network "https://github.com/liustack/modlens/blob/main/src/net/network.ts"
click node_doctor "https://github.com/liustack/modlens/blob/main/src/doctor.ts"
click node_cooldown "https://github.com/liustack/modlens/blob/main/src/cooldown.ts"

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_pasteclient,node_pasteplugin,node_recovery,node_user toneBlue
class node_cli,node_analyzer,node_prompt,node_harnessdata toneAmber
class node_autodiscover,node_autoroutes,node_providerregistry,node_providerimpl,node_visionservices toneMint
class node_config,node_guard,node_network,node_doctor,node_cooldown toneRose
class node_dsh,node_localclis toneIndigo
```

## Components

### Image intake

- [Paste listener](https://github.com/liustack/modlens/blob/main/dsh/client.js): `dsh/client.js`
- [Paste and tool routes](https://github.com/liustack/modlens/blob/main/dsh/index.js): `dsh/index.js`
- [Paste recovery](https://github.com/liustack/modlens/blob/main/src/recoverPaste/index.ts): `src/recoverPaste/index.ts`

### Vision analysis

- [ModLens CLI](https://github.com/liustack/modlens/blob/main/src/main.ts): `src/main.ts`
- [Image analyzer](https://github.com/liustack/modlens/blob/main/src/analyzer.ts): `src/analyzer.ts`
- [Evidence prompt](https://github.com/liustack/modlens/blob/main/src/prompt.ts): `src/prompt.ts`

### Vision engines

- [Route discovery](https://github.com/liustack/modlens/blob/main/src/auto/discover.ts): `src/auto/discover.ts`
- [Borrowed routes](https://github.com/liustack/modlens/blob/main/src/auto/routes.ts): `src/auto/routes.ts`
- [Provider registry](https://github.com/liustack/modlens/blob/main/src/providers/index.ts): `src/providers/index.ts`
- [Provider implementations](https://github.com/liustack/modlens/tree/main/src/providers): `src/providers`

### Safety and setup

- [Configuration](https://github.com/liustack/modlens/blob/main/src/config.ts): `src/config.ts`
- [Model guard](https://github.com/liustack/modlens/blob/main/src/guard/index.ts): `src/guard/index.ts`
- [Remote image safety](https://github.com/liustack/modlens/blob/main/src/net/network.ts): `src/net/network.ts`
- [Health diagnostics](https://github.com/liustack/modlens/blob/main/src/doctor.ts): `src/doctor.ts`
- [Failover cooldown](https://github.com/liustack/modlens/blob/main/src/cooldown.ts): `src/cooldown.ts`

### Other components

- **User**
- **DSH host**
- **Harness session stores**
- **Vision APIs**
- **Local vision CLIs**

## Connections

- User → Paste listener: pastes image
- Paste listener → Paste and tool routes: uploads bytes
- Paste and tool routes → DSH host: stores path
- DSH host → ModLens CLI: invokes read
- User → ModLens CLI: requests image read
- ModLens CLI → Configuration: loads settings
- ModLens CLI → Model guard: checks model
- ModLens CLI → Failover cooldown: builds cooldown
- ModLens CLI → Image analyzer: analyzes image
- Image analyzer → Evidence prompt: builds prompt
- Image analyzer → Provider registry: selects and runs
- Provider registry → Provider implementations: dispatches provider
- Provider implementations → Vision APIs: sends image request
- Provider implementations → Local vision CLIs: spawns vision CLI
- Image analyzer → Remote image safety: validates remote image
- Route discovery → Borrowed routes: supplies routes
- Borrowed routes → Provider registry: adds providers
- User → Paste recovery: requests recovered paste
- Paste recovery → Harness session stores: reads image records
- ModLens CLI → Health diagnostics: builds report
- Health diagnostics → Configuration: reads settings