# alexdevlabs/visualice architecture

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

- Interactive diagram: https://gitdiagram.com/alexdevlabs/visualice
- Repository: https://github.com/alexdevlabs/visualice

## Overview

visualice crawls a target site into a reusable route/state catalogue, captures screenshots across configured devices, and serves or exports the resulting run for inspection. The main workflow is CLI or library entry → crawl orchestration → route and state discovery → manifest/routes intent → capture → run storage → viewer. The README also describes agent-guided exploration and replay; the supplied tree has no distinct agent runtime module, so the graph represents human/agent steering through the routes file. Connections are limited to README statements and sampled imports or calls; unsampled feature links are omitted.

Main entry points: [`src/crawl/orchestrator.ts`](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/orchestrator.ts) (Crawl orchestration), [`src/cli.ts`](https://github.com/alexdevlabs/visualice/blob/main/src/cli.ts) (CLI commands), [`src/crawl/capture.ts`](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/capture.ts) (Screenshot capture), [`src/crawl/discover-routes.ts`](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover-routes.ts) (Route discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_api["Library API<br/>[index.ts]"]
  node_config["Config loading<br/>[config.ts]"]
end

subgraph group_crawl["Discovery and capture"]
  node_orchestrator["Crawl orchestration<br/>[orchestrator.ts]"]
  node_route_discovery["Route discovery<br/>[discover-routes.ts]"]
  node_state_discovery["State discovery<br/>[discover-states.ts]"]
  node_discovery["Discovery coordinator<br/>[discover.ts]"]
  node_auth["Login and session<br/>[auth.ts]"]
  node_capture["Screenshot capture<br/>[capture.ts]"]
  node_screens["Screen stitching<br/>[screens.ts]"]
  node_accessibility["Accessibility checks<br/>[accessibility.ts]"]
end

subgraph group_data["Catalogue and run data"]
  node_routes["Editable routes file<br/>[routes-file.ts]"]
  node_manifest[("Site manifest<br/>[manifest.ts]")]
  node_recipe["Navigation recipes<br/>[recipe.ts]"]
  node_runs[("Run catalogue<br/>[runs.ts]")]
  node_shared["Shared crawl utilities"]
end

subgraph group_results["Results and viewer"]
  node_viewer_service["Viewer data server<br/>[serve.ts]"]
  node_export["Static report export<br/>[export.ts]"]
  node_viewer_app["Viewer application<br/>[App.tsx]"]
  node_canvas["Zoomable canvas<br/>[Canvas.tsx]"]
  node_viewer_loader["Viewer data loading<br/>[load.ts]"]
end

node_user(("Engineer or agent"))
node_target(("Target website"))

node_user -->|"runs commands"| node_cli
node_user -->|"calls directly"| node_api
node_cli -->|"loads settings"| node_config
node_cli -->|"starts crawl"| node_orchestrator
node_api -->|"exposes pipeline"| node_orchestrator
node_orchestrator -->|"ensures session"| node_auth
node_orchestrator -->|"discovers site"| node_discovery
node_orchestrator -->|"runs capture"| node_capture
node_orchestrator -->|"applies route intent"| node_routes
node_orchestrator -->|"loads and merges"| node_manifest
node_orchestrator -->|"manages runs"| node_runs
node_discovery -->|"finds routes"| node_route_discovery
node_discovery -->|"probes states"| node_state_discovery
node_route_discovery -->|"navigates pages"| node_target
node_route_discovery -->|"navigates with"| node_recipe
node_auth -->|"replays login"| node_recipe
node_capture -->|"captures screens"| node_screens
node_capture -->|"checks captures"| node_accessibility
node_capture -->|"records results"| node_manifest
node_routes -->|"steers catalogue"| node_manifest
node_orchestrator -->|"uses shared helpers"| node_shared
node_viewer_service -->|"lists run data"| node_runs
node_cli -->|"starts viewer"| node_viewer_service
node_viewer_service -->|"serves application"| node_viewer_app
node_viewer_app -->|"loads catalogue"| node_viewer_loader
node_viewer_app -->|"renders canvas"| node_canvas
node_cli -->|"exports report"| node_export
node_export -->|"exports run"| node_runs

click node_cli "https://github.com/alexdevlabs/visualice/blob/main/src/cli.ts"
click node_api "https://github.com/alexdevlabs/visualice/blob/main/src/index.ts"
click node_config "https://github.com/alexdevlabs/visualice/blob/main/src/shared/config.ts"
click node_orchestrator "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/orchestrator.ts"
click node_route_discovery "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover-routes.ts"
click node_state_discovery "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover-states.ts"
click node_discovery "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover.ts"
click node_auth "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/auth.ts"
click node_capture "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/capture.ts"
click node_screens "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/screens.ts"
click node_accessibility "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/accessibility.ts"
click node_routes "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/routes-file.ts"
click node_manifest "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/manifest.ts"
click node_recipe "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/recipe.ts"
click node_runs "https://github.com/alexdevlabs/visualice/blob/main/src/crawl/runs.ts"
click node_shared "https://github.com/alexdevlabs/visualice/tree/main/src/shared"
click node_viewer_service "https://github.com/alexdevlabs/visualice/blob/main/src/serve.ts"
click node_export "https://github.com/alexdevlabs/visualice/blob/main/src/export.ts"
click node_viewer_app "https://github.com/alexdevlabs/visualice/blob/main/viewer/src/App.tsx"
click node_canvas "https://github.com/alexdevlabs/visualice/blob/main/viewer/src/Canvas.tsx"
click node_viewer_loader "https://github.com/alexdevlabs/visualice/blob/main/viewer/src/load.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_cli,node_api,node_config toneBlue
class node_orchestrator,node_route_discovery,node_state_discovery,node_discovery,node_auth,node_capture,node_screens,node_accessibility toneAmber
class node_routes,node_manifest,node_recipe,node_runs,node_shared toneMint
class node_viewer_service,node_export,node_viewer_app,node_canvas,node_viewer_loader toneRose
class node_user,node_target toneIndigo
```

## Components

### Entry and configuration

- [CLI commands](https://github.com/alexdevlabs/visualice/blob/main/src/cli.ts): `src/cli.ts`
- [Library API](https://github.com/alexdevlabs/visualice/blob/main/src/index.ts): `src/index.ts`
- [Config loading](https://github.com/alexdevlabs/visualice/blob/main/src/shared/config.ts): `src/shared/config.ts`

### Discovery and capture

- [Crawl orchestration](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/orchestrator.ts): `src/crawl/orchestrator.ts`
- [Route discovery](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover-routes.ts): `src/crawl/discover-routes.ts`
- [State discovery](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover-states.ts): `src/crawl/discover-states.ts`
- [Discovery coordinator](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/discover.ts): `src/crawl/discover.ts`
- [Login and session](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/auth.ts): `src/crawl/auth.ts`
- [Screenshot capture](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/capture.ts): `src/crawl/capture.ts`
- [Screen stitching](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/screens.ts): `src/crawl/screens.ts`
- [Accessibility checks](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/accessibility.ts): `src/crawl/accessibility.ts`

### Catalogue and run data

- [Editable routes file](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/routes-file.ts): `src/crawl/routes-file.ts`
- [Site manifest](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/manifest.ts): `src/crawl/manifest.ts`
- [Navigation recipes](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/recipe.ts): `src/crawl/recipe.ts`
- [Run catalogue](https://github.com/alexdevlabs/visualice/blob/main/src/crawl/runs.ts): `src/crawl/runs.ts`
- [Shared crawl utilities](https://github.com/alexdevlabs/visualice/tree/main/src/shared): `src/shared`

### Results and viewer

- [Viewer data server](https://github.com/alexdevlabs/visualice/blob/main/src/serve.ts): `src/serve.ts`
- [Static report export](https://github.com/alexdevlabs/visualice/blob/main/src/export.ts): `src/export.ts`
- [Viewer application](https://github.com/alexdevlabs/visualice/blob/main/viewer/src/App.tsx): `viewer/src/App.tsx`
- [Zoomable canvas](https://github.com/alexdevlabs/visualice/blob/main/viewer/src/Canvas.tsx): `viewer/src/Canvas.tsx`
- [Viewer data loading](https://github.com/alexdevlabs/visualice/blob/main/viewer/src/load.ts): `viewer/src/load.ts`

### Other components

- **Engineer or agent**
- **Target website**

## Connections

- Engineer or agent → CLI commands: runs commands (evidence: `README.md`)
- Engineer or agent → Library API: calls directly (evidence: `src/index.ts`)
- CLI commands → Config loading: loads settings (evidence: `src/cli.ts`)
- CLI commands → Crawl orchestration: starts crawl (evidence: `src/cli.ts`)
- Library API → Crawl orchestration: exposes pipeline (evidence: `src/index.ts`)
- Crawl orchestration → Login and session: ensures session (evidence: `src/crawl/orchestrator.ts`)
- Crawl orchestration → Discovery coordinator: discovers site (evidence: `src/crawl/orchestrator.ts`)
- Crawl orchestration → Screenshot capture: runs capture (evidence: `src/crawl/orchestrator.ts`)
- Crawl orchestration → Editable routes file: applies route intent (evidence: `src/crawl/orchestrator.ts`)
- Crawl orchestration → Site manifest: loads and merges (evidence: `src/crawl/orchestrator.ts`)
- Crawl orchestration → Run catalogue: manages runs (evidence: `src/crawl/orchestrator.ts`)
- Discovery coordinator → Route discovery: finds routes (evidence: `src/crawl/discover.ts`)
- Discovery coordinator → State discovery: probes states (evidence: `src/crawl/discover.ts`)
- Route discovery → Target website: navigates pages (evidence: `src/crawl/discover-routes.ts`)
- Route discovery → Navigation recipes: navigates with (evidence: `src/crawl/discover-routes.ts`)
- Login and session → Navigation recipes: replays login (evidence: `src/crawl/auth.ts`)
- Screenshot capture → Screen stitching: captures screens (evidence: `src/crawl/capture.ts`)
- Screenshot capture → Accessibility checks: checks captures (evidence: `src/crawl/capture.ts`)
- Screenshot capture → Site manifest: records results (evidence: `src/crawl/capture.ts`)
- Editable routes file → Site manifest: steers catalogue (evidence: `src/crawl/routes-file.ts`)
- Crawl orchestration → Shared crawl utilities: uses shared helpers (evidence: `src/crawl/orchestrator.ts`)
- Viewer data server → Run catalogue: lists run data (evidence: `src/serve.ts`)
- CLI commands → Viewer data server: starts viewer (evidence: `src/cli.ts`)
- Viewer data server → Viewer application: serves application (evidence: `src/serve.ts`)
- Viewer application → Viewer data loading: loads catalogue (evidence: `viewer/src/App.tsx`)
- Viewer application → Zoomable canvas: renders canvas (evidence: `viewer/src/App.tsx`)
- CLI commands → Static report export: exports report (evidence: `src/cli.ts`)
- Static report export → Run catalogue: exports run (evidence: `src/export.ts`)