# forwalkin/claude-local-bridge- architecture

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

- Interactive diagram: https://gitdiagram.com/forwalkin/claude-local-bridge-
- Repository: https://github.com/forwalkin/claude-local-bridge-

## Overview

Claude Local Bridge is a Node.js runtime foundation for safely exposing local Skills to an AI agent; it is not yet a chat-connected product. The intended use flow loads and validates declarative manifests, checks inputs and permissions, constrains paths to a sandbox, obtains human approval for destructive operations, then launches an isolated Python runner and audits outcomes. README documentation describes these as independently tested layers, not an already-wired end-to-end workflow. The graph reflects shown calls and documented capabilities; unsampled wiring and the future model/session interface are omitted.

Main entry points: [`backend-node/src/execution/executionEngine.js`](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/execution/executionEngine.js) (Execution Engine), [`backend-node/src/services/createSkillRegistry.js`](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/createSkillRegistry.js) (Registry Factory), [`backend-node/src/audit/auditLogger.js`](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/auditLogger.js) (Audit Logger), [`backend-node/src/services/skillLoader.js`](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillLoader.js) (Skill Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skills["Skill Definitions"]
  node_manifest["Workspace Cleaner"]
  node_schema["Skill Schema<br/>[skill.schema.json]"]
  node_config["Project Paths<br/>[paths.js]"]
  node_loader["Skill Loader<br/>[skillLoader.js]"]
  node_validator["Manifest Validator<br/>[skillValidator.js]"]
  node_registry["Skill Registry<br/>[skillRegistry.js]"]
  node_registry_factory["Registry Factory"]
end

subgraph group_security["Security Decisions"]
  node_permission_engine["Permission Engine"]
  node_permission_checks["Permission Checks"]
  node_path_policy["Path Policy<br/>[pathPolicy.js]"]
  node_path_resolution["Path Resolution<br/>[pathResolution.js]"]
  node_sandbox["Filesystem Sandbox"]
  node_confirmation["Confirmation Manager"]
  node_fingerprint["Operation Fingerprint"]
end

subgraph group_runtime["Execution Runtime"]
  node_engine["Execution Engine<br/>[executionEngine.js]"]
  node_runner_resolver["Runner Resolver<br/>[runnerPath.js]"]
end

subgraph group_audit["Audit"]
  node_audit_logger["Audit Logger<br/>[auditLogger.js]"]
  node_event_severity["Event Severity<br/>[eventSeverity.js]"]
  node_result_adapters["Result Adapters"]
  node_confirmation_adapter["Confirmation Adapter"]
end

node_developer(("Skill Author"))
node_child_process(("Python Child Process"))

node_developer -->|"declares skill"| node_manifest
node_registry_factory -->|"gets paths"| node_config
node_registry_factory -->|"creates and loads"| node_loader
node_loader -->|"reads manifests"| node_manifest
node_loader -->|"validates manifest"| node_validator
node_validator -->|"compiles against"| node_schema
node_registry_factory -->|"registers skills"| node_registry
node_registry_factory -->|"supplies validator"| node_validator
node_permission_engine -->|"runs checks"| node_permission_checks
node_path_policy -->|"resolves paths"| node_path_resolution
node_path_policy -->|"confines paths"| node_sandbox
node_confirmation -->|"fingerprints operation"| node_fingerprint
node_engine -->|"recomputes fingerprint"| node_fingerprint
node_engine -->|"consumes approval"| node_confirmation
node_engine -->|"resolves runner"| node_runner_resolver
node_engine -->|"spawns runner"| node_child_process
node_engine -->|"logs execution"| node_audit_logger
node_audit_logger -->|"looks up severity"| node_event_severity
node_result_adapters -.->|"adapts results"| node_audit_logger
node_confirmation_adapter -.->|"adapts events"| node_audit_logger

click node_manifest "https://github.com/forwalkin/claude-local-bridge-/blob/main/ai-skills/manifests/workspace_cleaner.json"
click node_schema "https://github.com/forwalkin/claude-local-bridge-/blob/main/ai-skills/schemas/skill.schema.json"
click node_config "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/config/paths.js"
click node_loader "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillLoader.js"
click node_validator "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillValidator.js"
click node_registry "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillRegistry.js"
click node_registry_factory "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/createSkillRegistry.js"
click node_permission_engine "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/permissionEngine.js"
click node_permission_checks "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/permissionChecks.js"
click node_path_policy "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/pathPolicy.js"
click node_path_resolution "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/pathResolution.js"
click node_confirmation "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/confirmationManager.js"
click node_fingerprint "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/operationFingerprint.js"
click node_engine "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/execution/executionEngine.js"
click node_runner_resolver "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/execution/runnerPath.js"
click node_audit_logger "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/auditLogger.js"
click node_event_severity "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/eventSeverity.js"
click node_result_adapters "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/resultEventAdapters.js"
click node_confirmation_adapter "https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/confirmationEventAdapter.js"

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_manifest,node_schema,node_config,node_loader,node_validator,node_registry,node_registry_factory toneBlue
class node_permission_engine,node_permission_checks,node_path_policy,node_path_resolution,node_sandbox,node_confirmation,node_fingerprint toneAmber
class node_engine,node_runner_resolver toneMint
class node_audit_logger,node_event_severity,node_result_adapters,node_confirmation_adapter toneRose
class node_developer,node_child_process toneIndigo
```

## Components

### Skill Definitions

- [Workspace Cleaner](https://github.com/forwalkin/claude-local-bridge-/blob/main/ai-skills/manifests/workspace_cleaner.json): `ai-skills/manifests/workspace_cleaner.json`
- [Skill Schema](https://github.com/forwalkin/claude-local-bridge-/blob/main/ai-skills/schemas/skill.schema.json): `ai-skills/schemas/skill.schema.json`
- [Project Paths](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/config/paths.js): `backend-node/src/config/paths.js`
- [Skill Loader](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillLoader.js): `backend-node/src/services/skillLoader.js`
- [Manifest Validator](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillValidator.js): `backend-node/src/services/skillValidator.js`
- [Skill Registry](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/skillRegistry.js): `backend-node/src/services/skillRegistry.js`
- [Registry Factory](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/services/createSkillRegistry.js): `backend-node/src/services/createSkillRegistry.js`

### Security Decisions

- [Permission Engine](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/permissionEngine.js): `backend-node/src/security/permissionEngine.js`
- [Permission Checks](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/permissionChecks.js): `backend-node/src/security/permissionChecks.js`
- [Path Policy](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/pathPolicy.js): `backend-node/src/security/pathPolicy.js`
- [Path Resolution](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/pathResolution.js): `backend-node/src/security/pathResolution.js`
- **Filesystem Sandbox**
- [Confirmation Manager](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/confirmationManager.js): `backend-node/src/security/confirmationManager.js`
- [Operation Fingerprint](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/security/operationFingerprint.js): `backend-node/src/security/operationFingerprint.js`

### Execution Runtime

- [Execution Engine](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/execution/executionEngine.js): `backend-node/src/execution/executionEngine.js`
- [Runner Resolver](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/execution/runnerPath.js): `backend-node/src/execution/runnerPath.js`

### Audit

- [Audit Logger](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/auditLogger.js): `backend-node/src/audit/auditLogger.js`
- [Event Severity](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/eventSeverity.js): `backend-node/src/audit/eventSeverity.js`
- [Result Adapters](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/resultEventAdapters.js): `backend-node/src/audit/resultEventAdapters.js`
- [Confirmation Adapter](https://github.com/forwalkin/claude-local-bridge-/blob/main/backend-node/src/audit/confirmationEventAdapter.js): `backend-node/src/audit/confirmationEventAdapter.js`

### Other components

- **Skill Author**
- **Python Child Process**

## Connections

- Skill Author → Workspace Cleaner: declares skill (evidence: `README.md`)
- Registry Factory → Project Paths: gets paths (evidence: `backend-node/src/services/createSkillRegistry.js`)
- Registry Factory → Skill Loader: creates and loads (evidence: `backend-node/src/services/createSkillRegistry.js`)
- Skill Loader → Workspace Cleaner: reads manifests (evidence: `backend-node/src/services/skillLoader.js`)
- Skill Loader → Manifest Validator: validates manifest (evidence: `backend-node/src/services/skillLoader.js`)
- Manifest Validator → Skill Schema: compiles against (evidence: `backend-node/src/services/skillValidator.js`)
- Registry Factory → Skill Registry: registers skills (evidence: `backend-node/src/services/createSkillRegistry.js`)
- Registry Factory → Manifest Validator: supplies validator (evidence: `backend-node/src/services/createSkillRegistry.js`)
- Permission Engine → Permission Checks: runs checks (evidence: `backend-node/src/security/permissionEngine.js`)
- Path Policy → Path Resolution: resolves paths (evidence: `backend-node/src/security/pathPolicy.js`)
- Path Policy → Filesystem Sandbox: confines paths (evidence: `README.md`)
- Confirmation Manager → Operation Fingerprint: fingerprints operation (evidence: `backend-node/src/security/confirmationManager.js`)
- Execution Engine → Operation Fingerprint: recomputes fingerprint (evidence: `backend-node/src/execution/executionEngine.js`)
- Execution Engine → Confirmation Manager: consumes approval (evidence: `backend-node/src/execution/executionEngine.js`)
- Execution Engine → Runner Resolver: resolves runner (evidence: `backend-node/src/execution/executionEngine.js`)
- Execution Engine → Python Child Process: spawns runner (evidence: `backend-node/src/execution/executionEngine.js`)
- Execution Engine → Audit Logger: logs execution (evidence: `backend-node/src/execution/executionEngine.js`)
- Audit Logger → Event Severity: looks up severity (evidence: `backend-node/src/audit/auditLogger.js`)
- Result Adapters → Audit Logger: adapts results
- Confirmation Adapter → Audit Logger: adapts events
