# corankai/ai-citation-evidence-validator architecture

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

- Interactive diagram: https://gitdiagram.com/corankai/ai-citation-evidence-validator
- Repository: https://github.com/corankai/ai-citation-evidence-validator

## Overview

#### Purpose and delivery model
This repository provides a dependency-free, browser-local validator for AI-search/AEO/GEO observation records. It accepts pasted JSON arrays or JSONL, evaluates explicit evidence-quality rules, and produces inspectable record/field findings rather than an aggregate visibility score. Static deployment is centered on `index.html`, with the published tool intended for GitHub Pages.

Paths: `index.html`, `script.js`, `style.css`

#### Primary browser entry point
`index.html` hosts the interactive input, validation controls, findings display, and local report-download surface. `script.js` is the application controller: it reads pasted input, selects JSON versus JSONL parsing, invokes validation, renders status/finding output, and creates downloadable JSON in the browser. `style.css` supplies the presentation layer without a framework or build artifact.

Paths: `index.html`, `script.js`, `style.css`

#### Observation ingestion boundary
The system’s sole operational input is a collection of observation objects representing prompt-answer runs. Parsing is deliberately client-side and must tolerate either one JSON array or line-delimited JSON objects. Invalid syntax and malformed records are surfaced as validation findings rather than sent to a service. This is the key privacy boundary: pasted evidence remains in the browser.

Paths: `script.js`, `README.md`

#### Validation engine and rule contract
The JavaScript validator enforces schema presence and cross-field consistency: required fields, boolean mention/citation flags, parseable/time-zoned timestamps, cited-domain arrays, target-domain agreement, evidence URLs, claim summaries, prompt-version stability, and duplicate run keys. Errors mark records invalid; warnings retain them for review; only records without findings are ready. Findings remain tied to individual records and fields.

Paths: `script.js`, `validator.go`, `validator_test.go`

#### Go validation package
A parallel Go package exposes the validation model and rules for programmatic consumers, documentation examples, or future non-browser integrations. `doc.go` defines the package-level public context; `validator.go` contains the implementation; Go tests establish the rule behavior. This package is separate from the static-page runtime rather than a backend for the web tool.

Paths: `doc.go`, `validator.go`, `validator_test.go`

#### Reporting and analyst workflow
The control flow is: paste observations → parse into records → validate each record plus duplicate keys across the set → classify invalid/needs-review/ready → render findings → optionally export a local JSON report. The output is an evidence review queue, not a truth or ranking determination; human reviewers remain responsible for checking answer artifacts and claim support.

Paths: `script.js`, `index.html`, `README.md`

#### Supporting research and publication assets
Documentation formalizes prompt-set versioning and usage guidance, while notebooks analyze adjacent AI-visibility evidence problems such as role drift, citation gaps, and controlled reruns. The repository uses static-site documentation and has lightweight development support through Vite/StackBlitz, but production requires no build step or application server.

Paths: `docs/prompt-set-versioning.md`, `notebooks/citation-gap-action-queue.ipynb`, `package.json`

Main entry points: [`index.html`](https://github.com/corankai/ai-citation-evidence-validator/blob/main/index.html) (Interactive page), [`script.js`](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js) (App controller), [`validator.go`](https://github.com/corankai/ai-citation-evidence-validator/blob/main/validator.go) (Go validator), [`docs/prompt-set-versioning.md`](https://github.com/corankai/ai-citation-evidence-validator/blob/main/docs/prompt-set-versioning.md) (Usage and versioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser-local tool"]
  node_page["Interactive page<br/>HTML entry<br/>[index.html]"]
  node_controller["App controller<br/>browser JavaScript<br/>[script.js]"]
  node_styles["Presentation<br/>CSS<br/>[style.css]"]
  node_pasted_input["Pasted observations<br/>local input"]
  node_parser["JSON / JSONL parser<br/>ingestion layer<br/>[script.js]"]
  node_browser_validator["Browser validator<br/>rule engine<br/>[script.js]"]
  node_findings["Record findings<br/>review queue<br/>[script.js]"]
  node_renderer["Findings renderer<br/>UI layer<br/>[script.js]"]
  node_report["Local JSON report<br/>browser download<br/>[script.js]"]
end

subgraph group_go["Go package"]
  node_go_api["Validation package API<br/>Go package docs<br/>[doc.go]"]
  node_go_validator["Go validator<br/>Go rule engine<br/>[validator.go]"]
  node_go_tests["Rule behavior tests<br/>Go tests<br/>[validator_test.go]"]
end

subgraph group_guidance["Guidance and research"]
  node_usage_docs["Usage and versioning<br/>documentation"]
  node_research["Citation-gap research<br/>notebook"]
  node_dev_support["Development support<br/>package tooling<br/>[package.json]"]
  node_readme["Repository guidance<br/>README<br/>[README.md]"]
end

node_page -->|"loads"| node_controller
node_page -->|"styles with"| node_styles
node_pasted_input -->|"paste"| node_parser
node_controller -->|"selects format"| node_parser
node_parser -->|"records and parse findings"| node_browser_validator
node_browser_validator -->|"classifies invalid / review / ready"| node_findings
node_controller -->|"drives"| node_renderer
node_findings -->|"renders"| node_renderer
node_renderer -->|"displays"| node_page
node_findings -->|"exports"| node_report
node_go_api -->|"documents"| node_go_validator
node_go_validator -->|"verified by"| node_go_tests
node_usage_docs -.->|"defines prompt-version guidance"| node_browser_validator
node_readme -.->|"documents local privacy boundary"| node_pasted_input
node_research -.->|"informs review practice"| node_usage_docs
node_dev_support -.->|"supports local development"| node_page

click node_page "https://github.com/corankai/ai-citation-evidence-validator/blob/main/index.html"
click node_controller "https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js"
click node_styles "https://github.com/corankai/ai-citation-evidence-validator/blob/main/style.css"
click node_parser "https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js"
click node_browser_validator "https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js"
click node_findings "https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js"
click node_renderer "https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js"
click node_report "https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js"
click node_go_api "https://github.com/corankai/ai-citation-evidence-validator/blob/main/doc.go"
click node_go_validator "https://github.com/corankai/ai-citation-evidence-validator/blob/main/validator.go"
click node_go_tests "https://github.com/corankai/ai-citation-evidence-validator/blob/main/validator_test.go"
click node_usage_docs "https://github.com/corankai/ai-citation-evidence-validator/blob/main/docs/prompt-set-versioning.md"
click node_research "https://github.com/corankai/ai-citation-evidence-validator/blob/main/notebooks/citation-gap-action-queue.ipynb"
click node_dev_support "https://github.com/corankai/ai-citation-evidence-validator/blob/main/package.json"
click node_readme "https://github.com/corankai/ai-citation-evidence-validator/blob/main/README.md"

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_page,node_controller,node_styles,node_pasted_input,node_parser,node_browser_validator,node_findings,node_renderer,node_report toneBlue
class node_go_api,node_go_validator,node_go_tests toneAmber
class node_usage_docs,node_research,node_dev_support,node_readme toneMint
```

## Components

### Browser-local tool

Static GitHub Pages deployment with no server.

- [Interactive page](https://github.com/corankai/ai-citation-evidence-validator/blob/main/index.html): HTML entry · Hosts input, controls, findings, and report download. · `index.html`
- [App controller](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js): browser JavaScript · Coordinates parsing, validation, rendering, and export. · `script.js`
- [Presentation](https://github.com/corankai/ai-citation-evidence-validator/blob/main/style.css): CSS · `style.css`
- **Pasted observations**: local input · JSON array or JSONL prompt-answer observation records.
- [JSON / JSONL parser](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js): ingestion layer · Keeps malformed syntax and records within the browser workflow. · `script.js`
- [Browser validator](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js): rule engine · Applies schema, evidence, consistency, and duplicate-key rules. · `script.js`
- [Record findings](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js): review queue · Field-level errors, warnings, and ready status per record. · `script.js`
- [Findings renderer](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js): UI layer · `script.js`
- [Local JSON report](https://github.com/corankai/ai-citation-evidence-validator/blob/main/script.js): browser download · Optional downloadable validation output. · `script.js`

### Go package

Parallel programmatic validator, not a web backend.

- [Validation package API](https://github.com/corankai/ai-citation-evidence-validator/blob/main/doc.go): Go package docs · Public context for programmatic consumers. · `doc.go`
- [Go validator](https://github.com/corankai/ai-citation-evidence-validator/blob/main/validator.go): Go rule engine · Parallel implementation of the validation model and rules. · `validator.go`
- [Rule behavior tests](https://github.com/corankai/ai-citation-evidence-validator/blob/main/validator_test.go): Go tests · `validator_test.go`

### Guidance and research

- [Usage and versioning](https://github.com/corankai/ai-citation-evidence-validator/blob/main/docs/prompt-set-versioning.md): documentation · Defines prompt-set versioning and workflow guidance. · `docs/prompt-set-versioning.md`
- [Citation-gap research](https://github.com/corankai/ai-citation-evidence-validator/blob/main/notebooks/citation-gap-action-queue.ipynb): notebook · Analyzes related evidence-review problems. · `notebooks/citation-gap-action-queue.ipynb`
- [Development support](https://github.com/corankai/ai-citation-evidence-validator/blob/main/package.json): package tooling · Lightweight Vite/StackBlitz support; not required in production. · `package.json`
- [Repository guidance](https://github.com/corankai/ai-citation-evidence-validator/blob/main/README.md): README · Explains local ingestion and analyst workflow. · `README.md`

## Connections

- Interactive page → App controller: loads
- Interactive page → Presentation: styles with
- Pasted observations → JSON / JSONL parser: paste
- App controller → JSON / JSONL parser: selects format
- JSON / JSONL parser → Browser validator: records and parse findings
- Browser validator → Record findings: classifies invalid / review / ready
- App controller → Findings renderer: drives
- Record findings → Findings renderer: renders
- Findings renderer → Interactive page: displays
- Record findings → Local JSON report: exports
- Validation package API → Go validator: documents
- Go validator → Rule behavior tests: verified by
- Usage and versioning → Browser validator: defines prompt-version guidance
- Repository guidance → Pasted observations: documents local privacy boundary
- Citation-gap research → Usage and versioning: informs review practice
- Development support → Interactive page: supports local development
