# nonsense3/veriq architecture

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

- Interactive diagram: https://gitdiagram.com/nonsense3/veriq
- Repository: https://github.com/nonsense3/veriq

## Overview

Veriq’s main workflow is a user submitting a suspicious URL or message through the web app; the scanner safely gathers evidence, performs deterministic analysis and correlation, and returns a report with a grounded AI explanation. Users can review investigation history and shared incidents, verify report commitments, and optionally seal or publish reports. The graph preserves the documented TLS, threat-intelligence, message-analysis, repository, and blockchain branches. Some implementation paths are represented only by README claims; those links are identified as documented rather than inferred from unsampled code.

Main entry points: [`apps/scanner/src/pipeline.ts`](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/pipeline.ts) (Investigation pipeline), [`apps/web/src/app/dashboard/page.tsx`](https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/dashboard/page.tsx) (Web application), [`apps/scanner/src/registry.ts`](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/registry.ts) (Report registry), [`apps/scanner/src/app.ts`](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/app.ts) (Scanner API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web application<br/>[page.tsx]"]
  node_report_ui["Report views<br/>[report-view.tsx]"]
  node_repository_ui["Threat repository UI<br/>[page.tsx]"]
  node_verification_ui["Commitment verifier UI<br/>[page.tsx]"]
end

subgraph group_scanner["Investigation service"]
  node_scanner_api["Scanner API<br/>[app.ts]"]
  node_pipeline["Investigation pipeline<br/>[pipeline.ts]"]
  node_safe_http["Safe HTTP inspection<br/>[safe-http.ts]"]
  node_tls_ct["TLS and CT checks<br/>[tls-probe.ts]"]
  node_dns_page["DNS and page checks<br/>[dns-info.ts]"]
end

subgraph group_analysis["Analysis and intelligence"]
  node_analysis_core["Deterministic analysis<br/>[assess.ts]"]
  node_url_analysis["URL and brand rules<br/>[url-rules.ts]"]
  node_message_analysis["Message analysis<br/>[message.ts]"]
  node_intel["Threat intelligence<br/>[providers.ts]"]
  node_correlation["Campaign correlation<br/>[correlation.ts]"]
  node_ai["Grounded explanations<br/>[explain.ts]"]
end

subgraph group_trust["Report trust"]
  node_store[("Report storage<br/>[store.ts]")]
  node_registry["Report registry<br/>[registry.ts]"]
  node_commitment["Commitment keys<br/>[registry-key.ts]"]
  node_verifier["Independent verifier<br/>[verify.mjs]"]
end

node_investigator(("Investigator"))
node_blockchain{{"Ethereum Sepolia"}}
node_ai_provider{{"Gemma AI service"}}

node_investigator -->|"submits investigation"| node_web
node_web -.->|"requests investigation"| node_scanner_api
node_scanner_api -->|"dispatches investigation"| node_pipeline
node_pipeline -->|"resolves safely"| node_safe_http
node_pipeline -->|"probes TLS and CT"| node_tls_ct
node_pipeline -->|"inspects domain and page"| node_dns_page
node_pipeline -->|"assesses report"| node_analysis_core
node_analysis_core -.->|"uses URL rules"| node_url_analysis
node_pipeline -.->|"analyzes messages"| node_message_analysis
node_pipeline -.->|"queries providers"| node_intel
node_pipeline -->|"correlates evidence"| node_correlation
node_pipeline -->|"requests explanation"| node_ai
node_ai -.->|"sends grounded prompt"| node_ai_provider
node_pipeline -->|"finalizes report"| node_store
node_pipeline -.->|"seals or publishes"| node_registry
node_registry -.->|"uses commitment keys"| node_commitment
node_registry -.->|"anchors commitment"| node_blockchain
node_web -.->|"presents report"| node_report_ui
node_web -.->|"opens repository"| node_repository_ui
node_web -.->|"opens verification"| node_verification_ui
node_verification_ui -.->|"verifies commitment"| node_verifier
node_repository_ui -.->|"loads and reviews incidents"| node_scanner_api
node_investigator -.->|"seals with wallet"| node_blockchain

click node_web "https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/dashboard/page.tsx"
click node_report_ui "https://github.com/nonsense3/veriq/blob/main/apps/web/src/components/report-view.tsx"
click node_repository_ui "https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/repository/page.tsx"
click node_verification_ui "https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/verify/page.tsx"
click node_scanner_api "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/app.ts"
click node_pipeline "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/pipeline.ts"
click node_safe_http "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/inspect/safe-http.ts"
click node_tls_ct "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/inspect/tls-probe.ts"
click node_dns_page "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/inspect/dns-info.ts"
click node_analysis_core "https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/assess.ts"
click node_url_analysis "https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/rules/url-rules.ts"
click node_message_analysis "https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/message.ts"
click node_intel "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/intel/providers.ts"
click node_correlation "https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/correlation.ts"
click node_ai "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/ai/explain.ts"
click node_store "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/store.ts"
click node_registry "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/registry.ts"
click node_commitment "https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/registry-key.ts"
click node_verifier "https://github.com/nonsense3/veriq/blob/main/apps/verifier/verify.mjs"

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_web,node_report_ui,node_repository_ui,node_verification_ui toneBlue
class node_scanner_api,node_pipeline,node_safe_http,node_tls_ct,node_dns_page toneAmber
class node_analysis_core,node_url_analysis,node_message_analysis,node_intel,node_correlation,node_ai toneMint
class node_store,node_registry,node_commitment,node_verifier toneRose
class node_investigator,node_blockchain,node_ai_provider toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/dashboard/page.tsx): `apps/web/src/app/dashboard/page.tsx`
- [Report views](https://github.com/nonsense3/veriq/blob/main/apps/web/src/components/report-view.tsx): `apps/web/src/components/report-view.tsx`
- [Threat repository UI](https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/repository/page.tsx): `apps/web/src/app/repository/page.tsx`
- [Commitment verifier UI](https://github.com/nonsense3/veriq/blob/main/apps/web/src/app/verify/page.tsx): `apps/web/src/app/verify/page.tsx`

### Investigation service

- [Scanner API](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/app.ts): `apps/scanner/src/app.ts`
- [Investigation pipeline](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/pipeline.ts): `apps/scanner/src/pipeline.ts`
- [Safe HTTP inspection](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/inspect/safe-http.ts): `apps/scanner/src/inspect/safe-http.ts`
- [TLS and CT checks](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/inspect/tls-probe.ts): `apps/scanner/src/inspect/tls-probe.ts`
- [DNS and page checks](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/inspect/dns-info.ts): `apps/scanner/src/inspect/dns-info.ts`

### Analysis and intelligence

- [Deterministic analysis](https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/assess.ts): `packages/analysis/src/assess.ts`
- [URL and brand rules](https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/rules/url-rules.ts): `packages/analysis/src/rules/url-rules.ts`
- [Message analysis](https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/message.ts): `packages/analysis/src/message.ts`
- [Threat intelligence](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/intel/providers.ts): `apps/scanner/src/intel/providers.ts`
- [Campaign correlation](https://github.com/nonsense3/veriq/blob/main/packages/analysis/src/correlation.ts): `packages/analysis/src/correlation.ts`
- [Grounded explanations](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/ai/explain.ts): `apps/scanner/src/ai/explain.ts`

### Report trust

- [Report storage](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/store.ts): `apps/scanner/src/store.ts`
- [Report registry](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/registry.ts): `apps/scanner/src/registry.ts`
- [Commitment keys](https://github.com/nonsense3/veriq/blob/main/apps/scanner/src/registry-key.ts): `apps/scanner/src/registry-key.ts`
- [Independent verifier](https://github.com/nonsense3/veriq/blob/main/apps/verifier/verify.mjs): `apps/verifier/verify.mjs`

### Other components

- **Investigator**
- **Ethereum Sepolia**
- **Gemma AI service**

## Connections

- Investigator → Web application: submits investigation
- Web application → Scanner API: requests investigation
- Scanner API → Investigation pipeline: dispatches investigation (evidence: `apps/scanner/src/app.ts`)
- Investigation pipeline → Safe HTTP inspection: resolves safely (evidence: `apps/scanner/src/pipeline.ts`)
- Investigation pipeline → TLS and CT checks: probes TLS and CT (evidence: `apps/scanner/src/pipeline.ts`)
- Investigation pipeline → DNS and page checks: inspects domain and page (evidence: `apps/scanner/src/pipeline.ts`)
- Investigation pipeline → Deterministic analysis: assesses report (evidence: `apps/scanner/src/pipeline.ts`)
- Deterministic analysis → URL and brand rules: uses URL rules
- Investigation pipeline → Message analysis: analyzes messages
- Investigation pipeline → Threat intelligence: queries providers (evidence: `apps/scanner/src/pipeline.ts`)
- Investigation pipeline → Campaign correlation: correlates evidence (evidence: `apps/scanner/src/pipeline.ts`)
- Investigation pipeline → Grounded explanations: requests explanation (evidence: `apps/scanner/src/pipeline.ts`)
- Grounded explanations → Gemma AI service: sends grounded prompt
- Investigation pipeline → Report storage: finalizes report (evidence: `apps/scanner/src/pipeline.ts`)
- Investigation pipeline → Report registry: seals or publishes (evidence: `apps/scanner/src/pipeline.ts`)
- Report registry → Commitment keys: uses commitment keys (evidence: `apps/scanner/src/registry.ts`)
- Report registry → Ethereum Sepolia: anchors commitment
- Web application → Report views: presents report
- Web application → Threat repository UI: opens repository
- Web application → Commitment verifier UI: opens verification
- Commitment verifier UI → Independent verifier: verifies commitment
- Threat repository UI → Scanner API: loads and reviews incidents
- Investigator → Ethereum Sepolia: seals with wallet