# vrsebeatriz/cypherguard-ia architecture

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

- Interactive diagram: https://gitdiagram.com/vrsebeatriz/cypherguard-ia
- Repository: https://github.com/vrsebeatriz/cypherguard-ia

## Overview

CypherGuard AI is a local-first JavaScript/Node.js security scanner with a CLI and API-backed dashboard. Its main workflow runs Semgrep, filters findings with AST taint analysis and local Ollama validation, audits dependencies against OSV.dev, then presents reports and optional patches for review and application. The repository also includes SARIF export, scan history, access control and audit logging. Edges rely on README workflow statements and the shown source/index references; some implementation details are unsampled, so those links are omitted where ownership is unclear.

Main entry points: [`src/app.ts`](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/app.ts) (API application), [`src/index.ts`](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/index.ts) (CLI), [`src/ai/validator.ts`](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/validator.ts) (AI validation), [`src/scanner/sca.ts`](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/sca.ts) (Dependency audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[index.ts]"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
  node_api["API application<br/>[app.ts]"]
  node_server["HTTP server<br/>[server.ts]"]
end

subgraph group_analysis["Security analysis"]
  node_semgrep["Semgrep scan<br/>[semgrep.ts]"]
  node_ast["AST taint analysis<br/>[ast.ts]"]
  node_entropy["Entropy analysis<br/>[entropy.ts]"]
  node_ai["AI validation<br/>[validator.ts]"]
  node_sca["Dependency audit<br/>[sca.ts]"]
end

subgraph group_outputs["Reports and remediation"]
  node_patcher["Patch review and apply<br/>[patcher.ts]"]
  node_sarif["SARIF export<br/>[sarif.ts]"]
  node_history[("Scan history<br/>[storage.ts]")]
end

subgraph group_services["Application services"]
  node_config["Configuration<br/>[loader.ts]"]
  node_health["Ollama health check<br/>[healthCheck.ts]"]
  node_ollama_manager["Ollama process manager<br/>[ollamaManager.ts]"]
  node_parser["AI result parser<br/>[parser.ts]"]
  node_knowledge["Security knowledge<br/>[knowledge.ts]"]
  node_custom_focus["Custom rule focus<br/>[customFocus.ts]"]
end

subgraph group_access["Access and safety"]
  node_auth[("Authentication and audit<br/>[service.ts]")]
  node_path_guard["Path guard<br/>[pathGuard.ts]"]
  node_git["Git safeguards<br/>[git.ts]"]
end

node_osv["OSV.dev"]
node_ollama["Ollama local model"]

node_cli -->|"runs scan"| node_semgrep
node_cli -->|"checks taint"| node_ast
node_cli -->|"checks secrets"| node_entropy
node_cli -->|"validates findings"| node_ai
node_cli -->|"audits dependencies"| node_sca
node_cli -->|"exports results"| node_sarif
node_cli -->|"offers patches"| node_patcher
node_cli -->|"checks worktree"| node_git
node_server -->|"serves routes"| node_api
node_dashboard -->|"uses API"| node_api
node_api -->|"runs scan"| node_semgrep
node_api -->|"checks taint"| node_ast
node_api -->|"validates findings"| node_ai
node_api -->|"audits dependencies"| node_sca
node_api -->|"applies patches"| node_patcher
node_api -->|"exports results"| node_sarif
node_api -->|"stores scans"| node_history
node_api -->|"checks access"| node_auth
node_api -->|"guards paths"| node_path_guard
node_api -->|"checks model"| node_health
node_api -->|"reads settings"| node_config
node_api -->|"manages model"| node_ollama_manager
node_sca -->|"queries vulnerabilities"| node_osv
node_ai -->|"loads settings"| node_config
node_ai -->|"asks local model"| node_ollama
node_ai -->|"parses response"| node_parser
node_ai -->|"uses guidelines"| node_knowledge
node_ai -->|"gets rule focus"| node_custom_focus
node_health -->|"reads settings"| node_config
node_ollama_manager -->|"starts process"| node_ollama

click node_cli "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/index.ts"
click node_dashboard "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/public/app.js"
click node_api "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/app.ts"
click node_server "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/server.ts"
click node_semgrep "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/semgrep.ts"
click node_ast "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/analyzer/ast.ts"
click node_entropy "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/analyzer/entropy.ts"
click node_ai "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/validator.ts"
click node_sca "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/sca.ts"
click node_patcher "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/patcher.ts"
click node_sarif "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/sarif.ts"
click node_history "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/history/storage.ts"
click node_config "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/config/loader.ts"
click node_health "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/utils/healthCheck.ts"
click node_ollama_manager "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/utils/ollamaManager.ts"
click node_parser "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/utils/parser.ts"
click node_knowledge "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/knowledge.ts"
click node_custom_focus "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/customFocus.ts"
click node_auth "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/auth/service.ts"
click node_path_guard "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/security/pathGuard.ts"
click node_git "https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/git.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_dashboard,node_api,node_server toneBlue
class node_semgrep,node_ast,node_entropy,node_ai,node_sca toneAmber
class node_patcher,node_sarif,node_history toneMint
class node_config,node_health,node_ollama_manager,node_parser,node_knowledge,node_custom_focus toneRose
class node_auth,node_path_guard,node_git,node_osv,node_ollama toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/index.ts): `src/index.ts`
- [Dashboard UI](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/public/app.js): `public/app.js`
- [API application](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/app.ts): `src/app.ts`
- [HTTP server](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/server.ts): `src/server.ts`

### Security analysis

- [Semgrep scan](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/semgrep.ts): `src/scanner/semgrep.ts`
- [AST taint analysis](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/analyzer/ast.ts): `src/analyzer/ast.ts`
- [Entropy analysis](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/analyzer/entropy.ts): `src/analyzer/entropy.ts`
- [AI validation](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/validator.ts): `src/ai/validator.ts`
- [Dependency audit](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/sca.ts): `src/scanner/sca.ts`

### Reports and remediation

- [Patch review and apply](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/patcher.ts): `src/scanner/patcher.ts`
- [SARIF export](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/sarif.ts): `src/scanner/sarif.ts`
- [Scan history](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/history/storage.ts): `src/history/storage.ts`

### Application services

- [Configuration](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/config/loader.ts): `src/config/loader.ts`
- [Ollama health check](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/utils/healthCheck.ts): `src/utils/healthCheck.ts`
- [Ollama process manager](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/utils/ollamaManager.ts): `src/utils/ollamaManager.ts`
- [AI result parser](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/utils/parser.ts): `src/utils/parser.ts`
- [Security knowledge](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/knowledge.ts): `src/ai/knowledge.ts`
- [Custom rule focus](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/ai/customFocus.ts): `src/ai/customFocus.ts`

### Access and safety

- [Authentication and audit](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/auth/service.ts): `src/auth/service.ts`
- [Path guard](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/security/pathGuard.ts): `src/security/pathGuard.ts`
- [Git safeguards](https://github.com/vrsebeatriz/cypherguard-ia/blob/main/src/scanner/git.ts): `src/scanner/git.ts`

### Other components

- **OSV.dev**
- **Ollama local model**

## Connections

- CLI → Semgrep scan: runs scan (evidence: `src/index.ts`)
- CLI → AST taint analysis: checks taint (evidence: `src/index.ts`)
- CLI → Entropy analysis: checks secrets (evidence: `src/index.ts`)
- CLI → AI validation: validates findings (evidence: `src/index.ts`)
- CLI → Dependency audit: audits dependencies (evidence: `src/index.ts`)
- CLI → SARIF export: exports results (evidence: `src/index.ts`)
- CLI → Patch review and apply: offers patches (evidence: `src/index.ts`)
- CLI → Git safeguards: checks worktree (evidence: `README.md`)
- HTTP server → API application: serves routes (evidence: `src/server.ts`)
- Dashboard UI → API application: uses API (evidence: `README.md`)
- API application → Semgrep scan: runs scan (evidence: `src/app.ts`)
- API application → AST taint analysis: checks taint (evidence: `src/app.ts`)
- API application → AI validation: validates findings (evidence: `src/app.ts`)
- API application → Dependency audit: audits dependencies (evidence: `src/app.ts`)
- API application → Patch review and apply: applies patches (evidence: `src/app.ts`)
- API application → SARIF export: exports results (evidence: `src/app.ts`)
- API application → Scan history: stores scans (evidence: `src/app.ts`)
- API application → Authentication and audit: checks access (evidence: `src/app.ts`)
- API application → Path guard: guards paths (evidence: `src/app.ts`)
- API application → Ollama health check: checks model (evidence: `src/app.ts`)
- API application → Configuration: reads settings (evidence: `src/app.ts`)
- API application → Ollama process manager: manages model (evidence: `src/app.ts`)
- Dependency audit → OSV.dev: queries vulnerabilities (evidence: `src/scanner/sca.ts`)
- AI validation → Configuration: loads settings (evidence: `src/ai/validator.ts`)
- AI validation → Ollama local model: asks local model (evidence: `README.md`)
- AI validation → AI result parser: parses response (evidence: `src/ai/validator.ts`)
- AI validation → Security knowledge: uses guidelines (evidence: `src/ai/validator.ts`)
- AI validation → Custom rule focus: gets rule focus (evidence: `src/ai/validator.ts`)
- Ollama health check → Configuration: reads settings (evidence: `src/utils/healthCheck.ts`)
- Ollama process manager → Ollama local model: starts process (evidence: `src/utils/ollamaManager.ts`)