# hiteater-wzm/eeo architecture

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

- Interactive diagram: https://gitdiagram.com/hiteater-wzm/eeo
- Repository: https://github.com/hiteater-wzm/eeo

## Overview

EEO combines an open brand-facts directory with AI visibility audits, a domain-ownership claim process, and an emerging reproducible measurement stack. The main audit flow accepts a brand and audit settings through one of several interfaces, runs questions against configured AI engines, then returns grades and answer evidence. The directory is a separate browse/search experience. Source excerpts establish the shared audit engine and key UI wiring; some major README-described subsystems are represented at their documented boundary because their implementation was not sampled.

Main entry points: [`core.cjs`](https://github.com/hiteater-wzm/eeo/blob/main/core.cjs) (Audit core), [`web/src/App.jsx`](https://github.com/hiteater-wzm/eeo/blob/main/web/src/App.jsx) (Web application), [`web/src/BrandDirectoryApp.jsx`](https://github.com/hiteater-wzm/eeo/blob/main/web/src/BrandDirectoryApp.jsx) (Directory application), [`datasets/registry`](https://github.com/hiteater-wzm/eeo/tree/main/datasets/registry) (Brand registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audit["Visibility audits"]
  node_cli["CLI audit<br/>[cli.cjs]"]
  node_server["Self-hosted API<br/>[server.cjs]"]
  node_mcp["MCP tools<br/>[server.cjs]"]
  node_action["GitHub Action<br/>[index.js]"]
  node_extension["Browser extension<br/>[background.js]"]
  node_local["Local audit app<br/>[eeo-local.js]"]
  node_auditcore["Audit core<br/>[core.cjs]"]
  node_engines{{"Configured AI engines"}}
  node_auditresults["Grades and answer report"]
end

subgraph group_directory["Brand directory"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_auditpages["Audit pages<br/>[StartPage.jsx]"]
  node_reportpage["Report view<br/>[ReportPage.jsx]"]
  node_crawlerpage["Crawler view<br/>[CrawlerPage.jsx]"]
  node_directoryapp["Directory application"]
  node_directoryhome["Directory home<br/>[Home.jsx]"]
  node_directorysearch["Brand search<br/>[Directory.jsx]"]
  node_branddetail["Brand details"]
end

subgraph group_claims["Claims and registry"]
  node_registry[("Brand registry")]
  node_claimverify["Domain verification<br/>[claim-verify.cjs]"]
  node_claimfinalize["Claim finalization<br/>[claim-finalize.cjs]"]
end

subgraph group_measurement["Reproducible measurement"]
  node_measurementrunner["Snapshot runner<br/>[snapshot-run.cjs]"]
  node_judge["Answer stance judging<br/>[judge.cjs]"]
  node_scoring["Snapshot scoring<br/>[score-snapshot.cjs]"]
  node_stats["Statistical functions<br/>[stats.cjs]"]
end

subgraph group_review["Registry review"]
  node_reviewprep["Review preparation"]
  node_arbiterprep["Arbitration preparation"]
  node_registrylib["Registry reader<br/>[registry-lib.cjs]"]
end

node_auditor(("Brand owner or auditor"))
node_claimant(("Brand claimant"))

node_auditor -->|"runs audit"| node_cli
node_auditor -->|"requests audit"| node_server
node_auditor -->|"calls tools"| node_mcp
node_auditor -->|"starts workflow"| node_action
node_auditor -->|"uses extension"| node_extension
node_auditor -->|"opens app"| node_local
node_cli -->|"calls"| node_auditcore
node_server -.->|"delegates"| node_auditcore
node_mcp -->|"calls"| node_auditcore
node_action -->|"calls"| node_auditcore
node_extension -.->|"connects to"| node_local
node_auditcore -->|"queries"| node_engines
node_auditcore -->|"returns report"| node_auditresults
node_webapp -->|"renders"| node_auditpages
node_webapp -->|"renders"| node_reportpage
node_webapp -->|"renders"| node_crawlerpage
node_auditpages -.->|"submits audit"| node_auditcore
node_reportpage -.->|"displays"| node_auditresults
node_auditor -->|"browses site"| node_webapp
node_webapp -->|"routes to"| node_directoryapp
node_directoryapp -->|"renders"| node_directoryhome
node_directoryapp -->|"renders"| node_directorysearch
node_directorysearch -->|"opens details"| node_branddetail
node_directoryapp -.->|"reads cards"| node_registry
node_claimant -->|"proves ownership"| node_claimverify
node_claimverify -.->|"verifies claim"| node_claimfinalize
node_claimfinalize -.->|"updates claim"| node_registry
node_measurementrunner -.->|"captures snapshots"| node_engines
node_measurementrunner -.->|"judges answers"| node_judge
node_judge -->|"requests judgments"| node_engines
node_judge -->|"computes agreement"| node_stats
node_scoring -.->|"uses statistics"| node_stats
node_auditor -.->|"reviews registry"| node_reviewprep
node_reviewprep -->|"reads registry"| node_registrylib
node_arbiterprep -->|"reads registry"| node_registrylib
node_reviewprep -->|"samples entries"| node_registry
node_arbiterprep -->|"restores evidence"| node_registry

click node_cli "https://github.com/hiteater-wzm/eeo/blob/main/cli.cjs"
click node_server "https://github.com/hiteater-wzm/eeo/blob/main/server.cjs"
click node_mcp "https://github.com/hiteater-wzm/eeo/blob/main/mcp/server.cjs"
click node_action "https://github.com/hiteater-wzm/eeo/blob/main/action/index.js"
click node_extension "https://github.com/hiteater-wzm/eeo/blob/main/extension/background/background.js"
click node_local "https://github.com/hiteater-wzm/eeo/blob/main/extension/full/eeo-local.js"
click node_auditcore "https://github.com/hiteater-wzm/eeo/blob/main/core.cjs"
click node_webapp "https://github.com/hiteater-wzm/eeo/blob/main/web/src/App.jsx"
click node_auditpages "https://github.com/hiteater-wzm/eeo/blob/main/web/src/StartPage.jsx"
click node_reportpage "https://github.com/hiteater-wzm/eeo/blob/main/web/src/ReportPage.jsx"
click node_crawlerpage "https://github.com/hiteater-wzm/eeo/blob/main/web/src/CrawlerPage.jsx"
click node_directoryapp "https://github.com/hiteater-wzm/eeo/blob/main/web/src/BrandDirectoryApp.jsx"
click node_directoryhome "https://github.com/hiteater-wzm/eeo/blob/main/web/src/pages/Home.jsx"
click node_directorysearch "https://github.com/hiteater-wzm/eeo/blob/main/web/src/pages/Directory.jsx"
click node_branddetail "https://github.com/hiteater-wzm/eeo/blob/main/web/src/components/BrandDetailDialog.jsx"
click node_registry "https://github.com/hiteater-wzm/eeo/tree/main/datasets/registry"
click node_claimverify "https://github.com/hiteater-wzm/eeo/blob/main/platform/claim-verify.cjs"
click node_claimfinalize "https://github.com/hiteater-wzm/eeo/blob/main/platform/claim-finalize.cjs"
click node_measurementrunner "https://github.com/hiteater-wzm/eeo/blob/main/tools/snapshot-run.cjs"
click node_judge "https://github.com/hiteater-wzm/eeo/blob/main/lib/judge.cjs"
click node_scoring "https://github.com/hiteater-wzm/eeo/blob/main/tools/score-snapshot.cjs"
click node_stats "https://github.com/hiteater-wzm/eeo/blob/main/lib/stats.cjs"
click node_reviewprep "https://github.com/hiteater-wzm/eeo/blob/main/tools/review2-prepare.cjs"
click node_arbiterprep "https://github.com/hiteater-wzm/eeo/blob/main/tools/review2-arbiter-prepare.cjs"
click node_registrylib "https://github.com/hiteater-wzm/eeo/blob/main/tools/registry-lib.cjs"

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_server,node_mcp,node_action,node_extension,node_local,node_auditcore,node_engines,node_auditresults toneBlue
class node_webapp,node_auditpages,node_reportpage,node_crawlerpage,node_directoryapp,node_directoryhome,node_directorysearch,node_branddetail toneAmber
class node_registry,node_claimverify,node_claimfinalize toneMint
class node_measurementrunner,node_judge,node_scoring,node_stats toneRose
class node_reviewprep,node_arbiterprep,node_registrylib,node_auditor,node_claimant toneIndigo
```

## Components

### Visibility audits

- [CLI audit](https://github.com/hiteater-wzm/eeo/blob/main/cli.cjs): `cli.cjs`
- [Self-hosted API](https://github.com/hiteater-wzm/eeo/blob/main/server.cjs): `server.cjs`
- [MCP tools](https://github.com/hiteater-wzm/eeo/blob/main/mcp/server.cjs): `mcp/server.cjs`
- [GitHub Action](https://github.com/hiteater-wzm/eeo/blob/main/action/index.js): `action/index.js`
- [Browser extension](https://github.com/hiteater-wzm/eeo/blob/main/extension/background/background.js): `extension/background/background.js`
- [Local audit app](https://github.com/hiteater-wzm/eeo/blob/main/extension/full/eeo-local.js): `extension/full/eeo-local.js`
- [Audit core](https://github.com/hiteater-wzm/eeo/blob/main/core.cjs): `core.cjs`
- **Configured AI engines**
- **Grades and answer report**

### Brand directory

- [Web application](https://github.com/hiteater-wzm/eeo/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Audit pages](https://github.com/hiteater-wzm/eeo/blob/main/web/src/StartPage.jsx): `web/src/StartPage.jsx`
- [Report view](https://github.com/hiteater-wzm/eeo/blob/main/web/src/ReportPage.jsx): `web/src/ReportPage.jsx`
- [Crawler view](https://github.com/hiteater-wzm/eeo/blob/main/web/src/CrawlerPage.jsx): `web/src/CrawlerPage.jsx`
- [Directory application](https://github.com/hiteater-wzm/eeo/blob/main/web/src/BrandDirectoryApp.jsx): `web/src/BrandDirectoryApp.jsx`
- [Directory home](https://github.com/hiteater-wzm/eeo/blob/main/web/src/pages/Home.jsx): `web/src/pages/Home.jsx`
- [Brand search](https://github.com/hiteater-wzm/eeo/blob/main/web/src/pages/Directory.jsx): `web/src/pages/Directory.jsx`
- [Brand details](https://github.com/hiteater-wzm/eeo/blob/main/web/src/components/BrandDetailDialog.jsx): `web/src/components/BrandDetailDialog.jsx`

### Claims and registry

- [Brand registry](https://github.com/hiteater-wzm/eeo/tree/main/datasets/registry): `datasets/registry`
- [Domain verification](https://github.com/hiteater-wzm/eeo/blob/main/platform/claim-verify.cjs): `platform/claim-verify.cjs`
- [Claim finalization](https://github.com/hiteater-wzm/eeo/blob/main/platform/claim-finalize.cjs): `platform/claim-finalize.cjs`

### Reproducible measurement

- [Snapshot runner](https://github.com/hiteater-wzm/eeo/blob/main/tools/snapshot-run.cjs): `tools/snapshot-run.cjs`
- [Answer stance judging](https://github.com/hiteater-wzm/eeo/blob/main/lib/judge.cjs): `lib/judge.cjs`
- [Snapshot scoring](https://github.com/hiteater-wzm/eeo/blob/main/tools/score-snapshot.cjs): `tools/score-snapshot.cjs`
- [Statistical functions](https://github.com/hiteater-wzm/eeo/blob/main/lib/stats.cjs): `lib/stats.cjs`

### Registry review

- [Review preparation](https://github.com/hiteater-wzm/eeo/blob/main/tools/review2-prepare.cjs): `tools/review2-prepare.cjs`
- [Arbitration preparation](https://github.com/hiteater-wzm/eeo/blob/main/tools/review2-arbiter-prepare.cjs): `tools/review2-arbiter-prepare.cjs`
- [Registry reader](https://github.com/hiteater-wzm/eeo/blob/main/tools/registry-lib.cjs): `tools/registry-lib.cjs`

### Other components

- **Brand owner or auditor**
- **Brand claimant**

## Connections

- Brand owner or auditor → CLI audit: runs audit (evidence: `README.md`)
- Brand owner or auditor → Self-hosted API: requests audit (evidence: `README.md`)
- Brand owner or auditor → MCP tools: calls tools (evidence: `README.md`)
- Brand owner or auditor → GitHub Action: starts workflow (evidence: `README.md`)
- Brand owner or auditor → Browser extension: uses extension (evidence: `README.md`)
- Brand owner or auditor → Local audit app: opens app (evidence: `README.md`)
- CLI audit → Audit core: calls (evidence: `core.cjs`)
- Self-hosted API → Audit core: delegates
- MCP tools → Audit core: calls (evidence: `mcp/server.cjs`)
- GitHub Action → Audit core: calls (evidence: `action/index.js`)
- Browser extension → Local audit app: connects to
- Audit core → Configured AI engines: queries (evidence: `core.cjs`)
- Audit core → Grades and answer report: returns report
- Web application → Audit pages: renders (evidence: `web/src/App.jsx`)
- Web application → Report view: renders (evidence: `web/src/App.jsx`)
- Web application → Crawler view: renders (evidence: `web/src/App.jsx`)
- Audit pages → Audit core: submits audit
- Report view → Grades and answer report: displays
- Brand owner or auditor → Web application: browses site (evidence: `README.md`)
- Web application → Directory application: routes to (evidence: `web/src/App.jsx`)
- Directory application → Directory home: renders (evidence: `web/src/BrandDirectoryApp.jsx`)
- Directory application → Brand search: renders (evidence: `web/src/BrandDirectoryApp.jsx`)
- Brand search → Brand details: opens details (evidence: `web/src/pages/Directory.jsx`)
- Directory application → Brand registry: reads cards
- Brand claimant → Domain verification: proves ownership (evidence: `README.md`)
- Domain verification → Claim finalization: verifies claim
- Claim finalization → Brand registry: updates claim
- Snapshot runner → Configured AI engines: captures snapshots
- Snapshot runner → Answer stance judging: judges answers
- Answer stance judging → Configured AI engines: requests judgments (evidence: `lib/judge.cjs`)
- Answer stance judging → Statistical functions: computes agreement (evidence: `lib/judge.cjs`)
- Snapshot scoring → Statistical functions: uses statistics
- Brand owner or auditor → Review preparation: reviews registry
- Review preparation → Registry reader: reads registry (evidence: `tools/review2-prepare.cjs`)
- Arbitration preparation → Registry reader: reads registry (evidence: `tools/review2-arbiter-prepare.cjs`)
- Review preparation → Brand registry: samples entries (evidence: `tools/review2-prepare.cjs`)
- Arbitration preparation → Brand registry: restores evidence (evidence: `tools/review2-arbiter-prepare.cjs`)
