# 3xo13/archpulse architecture

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

- Interactive diagram: https://gitdiagram.com/3xo13/archpulse
- Repository: https://github.com/3xo13/archpulse
- Video tour (about a minute): https://gitdiagram.com/3xo13/archpulse/video

## Overview

ArchPulse is a Bob IDE add-on and local CLI for finding dependency-rule violations, turning them into repair cases, and checking proposed fixes. The main workflow is scan → capture a baseline → generate and inspect a case → repair in Bob → verify with configured checks and a rescan; architecture-only comparison is also available. CLI and MCP are separate entry points into these capabilities. A React viewer presents example or imported results. The README documents these product areas; sampled source confirms entry-point wiring and selected viewer and demo behavior, while some core internals are unsampled.

Main entry points: [`src/cli/index.ts`](https://github.com/3xo13/archpulse/blob/main/src/cli/index.ts) (CLI commands), [`src/core/cases.ts`](https://github.com/3xo13/archpulse/blob/main/src/core/cases.ts) (Case generation), [`src/core/verify.ts`](https://github.com/3xo13/archpulse/blob/main/src/core/verify.ts) (Repair verification), [`src/cli/scan.ts`](https://github.com/3xo13/archpulse/blob/main/src/cli/scan.ts) (Repository scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI commands<br/>[index.ts]"]
  node_mcp["MCP tools<br/>[server.ts]"]
end

subgraph group_analysis["Scan and cases"]
  node_scan["Repository scan<br/>[scan.ts]"]
  node_scanner["Dependency scanner"]
  node_cases["Case generation<br/>[cases.ts]"]
  node_packet["Case packet<br/>[casePacket.ts]"]
  node_grouping["Violation grouping<br/>[grouping.ts]"]
end

subgraph group_repair["Verification"]
  node_compare["Architecture comparison<br/>[compare.ts]"]
  node_verify["Repair verification<br/>[verify.ts]"]
  node_checks["Test and typecheck runner<br/>[process.ts]"]
end

subgraph group_artifacts["Artifacts and storage"]
  node_baseline["Baseline snapshot<br/>[snapshot.ts]"]
  node_artifacts["Artifact publisher<br/>[artifacts.ts]"]
  node_storage["Workspace storage<br/>[storage.ts]"]
  node_workspace["Workspace validation<br/>[workspace.ts]"]
end

subgraph group_viewer["Results viewer"]
  node_viewer["Results viewer<br/>[App.tsx]"]
  node_import["Report import<br/>[ImportReport.tsx]"]
  node_graph["Before/after graph<br/>[GraphView.tsx]"]
  node_diff["Violation diff<br/>[ViolationDiff.tsx]"]
end

node_developer(("Developer"))
node_bob(("Bob IDE"))
node_demo_ui["Demo order service<br/>[orderService.ts]"]
node_demo_domain["Demo order domain<br/>[order.ts]"]
node_demo_shared["Demo shared types<br/>[types.ts]"]

node_developer -->|"runs commands"| node_cli
node_bob -->|"invokes tools"| node_mcp
node_cli -->|"runs scan"| node_scan
node_mcp -->|"runs scan"| node_scan
node_scan -->|"scans dependencies"| node_scanner
node_scanner -->|"returns findings"| node_baseline
node_scan -->|"captures snapshot"| node_baseline
node_cli -->|"generates cases"| node_cases
node_mcp -->|"generates cases"| node_cases
node_cases -->|"reads snapshot"| node_baseline
node_cases -->|"groups violations"| node_grouping
node_cases -->|"builds packet"| node_packet
node_cases -->|"publishes cases"| node_storage
node_cli -->|"compares snapshots"| node_compare
node_cli -->|"verifies repair"| node_verify
node_mcp -->|"verifies repair"| node_verify
node_verify -->|"runs checks"| node_checks
node_verify -->|"rescans repository"| node_scan
node_verify -->|"compares results"| node_compare
node_verify -->|"writes report"| node_artifacts
node_artifacts -->|"publishes files"| node_storage
node_scan -->|"stores baseline"| node_storage
node_mcp -->|"validates workspace"| node_workspace
node_cli -->|"resolves workspace"| node_workspace
node_developer -->|"opens results"| node_viewer
node_viewer -->|"accepts artifacts"| node_import
node_viewer -->|"renders graph"| node_graph
node_viewer -->|"renders changes"| node_diff
node_demo_ui -->|"calls order operations"| node_demo_domain
node_demo_domain -->|"uses shared types"| node_demo_shared

click node_cli "https://github.com/3xo13/archpulse/blob/main/src/cli/index.ts"
click node_mcp "https://github.com/3xo13/archpulse/blob/main/src/mcp/server.ts"
click node_scan "https://github.com/3xo13/archpulse/blob/main/src/cli/scan.ts"
click node_baseline "https://github.com/3xo13/archpulse/blob/main/src/core/snapshot.ts"
click node_cases "https://github.com/3xo13/archpulse/blob/main/src/core/cases.ts"
click node_packet "https://github.com/3xo13/archpulse/blob/main/src/core/casePacket.ts"
click node_grouping "https://github.com/3xo13/archpulse/blob/main/src/core/grouping.ts"
click node_compare "https://github.com/3xo13/archpulse/blob/main/src/core/compare.ts"
click node_verify "https://github.com/3xo13/archpulse/blob/main/src/core/verify.ts"
click node_checks "https://github.com/3xo13/archpulse/blob/main/src/core/process.ts"
click node_artifacts "https://github.com/3xo13/archpulse/blob/main/src/core/artifacts.ts"
click node_storage "https://github.com/3xo13/archpulse/blob/main/src/core/storage.ts"
click node_workspace "https://github.com/3xo13/archpulse/blob/main/src/core/workspace.ts"
click node_viewer "https://github.com/3xo13/archpulse/blob/main/src/viewer/App.tsx"
click node_import "https://github.com/3xo13/archpulse/blob/main/src/viewer/components/ImportReport.tsx"
click node_graph "https://github.com/3xo13/archpulse/blob/main/src/viewer/components/GraphView.tsx"
click node_diff "https://github.com/3xo13/archpulse/blob/main/src/viewer/components/ViolationDiff.tsx"
click node_demo_ui "https://github.com/3xo13/archpulse/blob/main/demo/packages/ui/src/orderService.ts"
click node_demo_domain "https://github.com/3xo13/archpulse/blob/main/demo/packages/domain/src/order.ts"
click node_demo_shared "https://github.com/3xo13/archpulse/blob/main/demo/packages/shared/src/types.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_mcp toneBlue
class node_scan,node_scanner,node_cases,node_packet,node_grouping toneAmber
class node_compare,node_verify,node_checks toneMint
class node_baseline,node_artifacts,node_storage,node_workspace toneRose
class node_viewer,node_import,node_graph,node_diff,node_developer,node_bob toneIndigo
class node_demo_ui,node_demo_domain,node_demo_shared toneTeal
```

## Components

### User entry points

- [CLI commands](https://github.com/3xo13/archpulse/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [MCP tools](https://github.com/3xo13/archpulse/blob/main/src/mcp/server.ts): `src/mcp/server.ts`

### Scan and cases

- [Repository scan](https://github.com/3xo13/archpulse/blob/main/src/cli/scan.ts): `src/cli/scan.ts`
- **Dependency scanner**
- [Case generation](https://github.com/3xo13/archpulse/blob/main/src/core/cases.ts): `src/core/cases.ts`
- [Case packet](https://github.com/3xo13/archpulse/blob/main/src/core/casePacket.ts): `src/core/casePacket.ts`
- [Violation grouping](https://github.com/3xo13/archpulse/blob/main/src/core/grouping.ts): `src/core/grouping.ts`

### Verification

- [Architecture comparison](https://github.com/3xo13/archpulse/blob/main/src/core/compare.ts): `src/core/compare.ts`
- [Repair verification](https://github.com/3xo13/archpulse/blob/main/src/core/verify.ts): `src/core/verify.ts`
- [Test and typecheck runner](https://github.com/3xo13/archpulse/blob/main/src/core/process.ts): `src/core/process.ts`

### Artifacts and storage

- [Baseline snapshot](https://github.com/3xo13/archpulse/blob/main/src/core/snapshot.ts): `src/core/snapshot.ts`
- [Artifact publisher](https://github.com/3xo13/archpulse/blob/main/src/core/artifacts.ts): `src/core/artifacts.ts`
- [Workspace storage](https://github.com/3xo13/archpulse/blob/main/src/core/storage.ts): `src/core/storage.ts`
- [Workspace validation](https://github.com/3xo13/archpulse/blob/main/src/core/workspace.ts): `src/core/workspace.ts`

### Results viewer

- [Results viewer](https://github.com/3xo13/archpulse/blob/main/src/viewer/App.tsx): `src/viewer/App.tsx`
- [Report import](https://github.com/3xo13/archpulse/blob/main/src/viewer/components/ImportReport.tsx): `src/viewer/components/ImportReport.tsx`
- [Before/after graph](https://github.com/3xo13/archpulse/blob/main/src/viewer/components/GraphView.tsx): `src/viewer/components/GraphView.tsx`
- [Violation diff](https://github.com/3xo13/archpulse/blob/main/src/viewer/components/ViolationDiff.tsx): `src/viewer/components/ViolationDiff.tsx`

### Other components

- **Developer**
- **Bob IDE**
- [Demo order service](https://github.com/3xo13/archpulse/blob/main/demo/packages/ui/src/orderService.ts): `demo/packages/ui/src/orderService.ts`
- [Demo order domain](https://github.com/3xo13/archpulse/blob/main/demo/packages/domain/src/order.ts): `demo/packages/domain/src/order.ts`
- [Demo shared types](https://github.com/3xo13/archpulse/blob/main/demo/packages/shared/src/types.ts): `demo/packages/shared/src/types.ts`

## Connections

- Developer → CLI commands: runs commands
- Bob IDE → MCP tools: invokes tools
- CLI commands → Repository scan: runs scan
- MCP tools → Repository scan: runs scan
- Repository scan → Dependency scanner: scans dependencies
- Dependency scanner → Baseline snapshot: returns findings
- Repository scan → Baseline snapshot: captures snapshot
- CLI commands → Case generation: generates cases
- MCP tools → Case generation: generates cases
- Case generation → Baseline snapshot: reads snapshot
- Case generation → Violation grouping: groups violations
- Case generation → Case packet: builds packet
- Case generation → Workspace storage: publishes cases
- CLI commands → Architecture comparison: compares snapshots
- CLI commands → Repair verification: verifies repair
- MCP tools → Repair verification: verifies repair
- Repair verification → Test and typecheck runner: runs checks
- Repair verification → Repository scan: rescans repository
- Repair verification → Architecture comparison: compares results
- Repair verification → Artifact publisher: writes report
- Artifact publisher → Workspace storage: publishes files
- Repository scan → Workspace storage: stores baseline
- MCP tools → Workspace validation: validates workspace
- CLI commands → Workspace validation: resolves workspace
- Developer → Results viewer: opens results
- Results viewer → Report import: accepts artifacts
- Results viewer → Before/after graph: renders graph
- Results viewer → Violation diff: renders changes
- Demo order service → Demo order domain: calls order operations
- Demo order domain → Demo shared types: uses shared types