# abdi219/parity architecture

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

- Interactive diagram: https://gitdiagram.com/abdi219/parity
- Repository: https://github.com/abdi219/parity

## Overview

Parity is a static API-documentation drift auditor. A user selects the demo or a public repository; the audit endpoint discovers or reads files, extracts documented and implemented contracts, compares them deterministically, and returns findings with provenance. The UI can apply suggested documentation patches and submit the patched text for a closed-loop re-audit. The route handler owns orchestration; the available excerpts do not show every call site, so documented workflow links use README evidence where needed.

Main entry points: [`web/src/app/api/audit/route.ts`](https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts) (Audit endpoint), [`web/src/app/page.tsx`](https://github.com/abdi219/parity/blob/main/web/src/app/page.tsx) (Audit UI), [`web/src/lib/driftEngine.ts`](https://github.com/abdi219/parity/blob/main/web/src/lib/driftEngine.ts) (Provenanced findings), [`web/src/lib/docExtractor.ts`](https://github.com/abdi219/parity/blob/main/web/src/lib/docExtractor.ts) (Documentation extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Audit interface"]
  node_ui["Audit UI<br/>[page.tsx]"]
  node_report_view["Findings and map<br/>[page.tsx]"]
end

subgraph group_orchestration["Audit orchestration"]
  node_audit_api["Audit endpoint<br/>[route.ts]"]
  node_demo_api["Demo source endpoint<br/>[route.ts]"]
  node_repo_discovery["Repository discovery<br/>[route.ts]"]
  node_repo_fetch["Selected file fetch<br/>[route.ts]"]
  node_demo_docs["Demo API documentation<br/>[README.md]"]
  node_demo_code["Demo auth handlers<br/>[auth.ts]"]
end

subgraph group_extraction["Contract extraction"]
  node_doc_extraction["Documentation extraction<br/>[docExtractor.ts]"]
  node_code_extraction["Source extraction<br/>[codeExtractor.ts]"]
  node_contract_schema["Normalized contracts<br/>[contract.ts]"]
end

subgraph group_analysis["Comparison and repair"]
  node_drift["Deterministic drift engine<br/>[driftEngine.ts]"]
  node_findings["Provenanced findings<br/>[driftEngine.ts]"]
  node_patcher["Patch and diff engine<br/>[patchEngine.ts]"]
end

node_user(("Engineer"))
node_github["GitHub"]
node_groq["Groq fallback"]

node_user -->|"starts audit"| node_ui
node_ui -->|"submits audit"| node_audit_api
node_ui -->|"loads demo docs"| node_demo_api
node_demo_api -->|"reads demo docs"| node_demo_docs
node_audit_api -->|"discovers files"| node_repo_discovery
node_repo_discovery -->|"requests tree"| node_github
node_audit_api -->|"fetches selected files"| node_repo_fetch
node_repo_fetch -->|"fetches file content"| node_github
node_audit_api -->|"extracts documentation"| node_doc_extraction
node_audit_api -->|"extracts implementation"| node_code_extraction
node_doc_extraction -.->|"uses prose fallback"| node_groq
node_code_extraction -.->|"uses targeted fallback"| node_groq
node_doc_extraction -->|"produces contracts"| node_contract_schema
node_code_extraction -->|"produces contracts"| node_contract_schema
node_audit_api -->|"compares contracts"| node_drift
node_drift -->|"reports drift"| node_findings
node_audit_api -->|"returns audit report"| node_findings
node_findings -->|"displays evidence"| node_report_view
node_report_view -->|"renders in"| node_ui
node_ui -->|"applies patches"| node_patcher
node_ui -->|"submits re-audit"| node_audit_api
node_demo_code -.->|"supplies implementation evidence"| node_findings
node_demo_docs -.->|"supplies documentation evidence"| node_findings

click node_ui "https://github.com/abdi219/parity/blob/main/web/src/app/page.tsx"
click node_report_view "https://github.com/abdi219/parity/blob/main/web/src/app/page.tsx"
click node_audit_api "https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts"
click node_demo_api "https://github.com/abdi219/parity/blob/main/web/src/app/api/audit-source/route.ts"
click node_repo_discovery "https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts"
click node_repo_fetch "https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts"
click node_doc_extraction "https://github.com/abdi219/parity/blob/main/web/src/lib/docExtractor.ts"
click node_code_extraction "https://github.com/abdi219/parity/blob/main/web/src/lib/codeExtractor.ts"
click node_contract_schema "https://github.com/abdi219/parity/blob/main/web/src/types/contract.ts"
click node_drift "https://github.com/abdi219/parity/blob/main/web/src/lib/driftEngine.ts"
click node_findings "https://github.com/abdi219/parity/blob/main/web/src/lib/driftEngine.ts"
click node_patcher "https://github.com/abdi219/parity/blob/main/web/src/lib/patchEngine.ts"
click node_demo_docs "https://github.com/abdi219/parity/blob/main/dummy-auth-service/README.md"
click node_demo_code "https://github.com/abdi219/parity/blob/main/dummy-auth-service/src/auth.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_ui,node_report_view toneBlue
class node_audit_api,node_demo_api,node_repo_discovery,node_repo_fetch,node_demo_docs,node_demo_code toneAmber
class node_doc_extraction,node_code_extraction,node_contract_schema toneMint
class node_drift,node_findings,node_patcher toneRose
class node_user,node_github,node_groq toneIndigo
```

## Components

### Audit interface

- [Audit UI](https://github.com/abdi219/parity/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`
- [Findings and map](https://github.com/abdi219/parity/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`

### Audit orchestration

- [Audit endpoint](https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts): `web/src/app/api/audit/route.ts`
- [Demo source endpoint](https://github.com/abdi219/parity/blob/main/web/src/app/api/audit-source/route.ts): `web/src/app/api/audit-source/route.ts`
- [Repository discovery](https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts): `web/src/app/api/audit/route.ts`
- [Selected file fetch](https://github.com/abdi219/parity/blob/main/web/src/app/api/audit/route.ts): `web/src/app/api/audit/route.ts`
- [Demo API documentation](https://github.com/abdi219/parity/blob/main/dummy-auth-service/README.md): `dummy-auth-service/README.md`
- [Demo auth handlers](https://github.com/abdi219/parity/blob/main/dummy-auth-service/src/auth.ts): `dummy-auth-service/src/auth.ts`

### Contract extraction

- [Documentation extraction](https://github.com/abdi219/parity/blob/main/web/src/lib/docExtractor.ts): `web/src/lib/docExtractor.ts`
- [Source extraction](https://github.com/abdi219/parity/blob/main/web/src/lib/codeExtractor.ts): `web/src/lib/codeExtractor.ts`
- [Normalized contracts](https://github.com/abdi219/parity/blob/main/web/src/types/contract.ts): `web/src/types/contract.ts`

### Comparison and repair

- [Deterministic drift engine](https://github.com/abdi219/parity/blob/main/web/src/lib/driftEngine.ts): `web/src/lib/driftEngine.ts`
- [Provenanced findings](https://github.com/abdi219/parity/blob/main/web/src/lib/driftEngine.ts): `web/src/lib/driftEngine.ts`
- [Patch and diff engine](https://github.com/abdi219/parity/blob/main/web/src/lib/patchEngine.ts): `web/src/lib/patchEngine.ts`

### Other components

- **Engineer**
- **GitHub**
- **Groq fallback**

## Connections

- Engineer → Audit UI: starts audit (evidence: `README.md`)
- Audit UI → Audit endpoint: submits audit (evidence: `README.md`)
- Audit UI → Demo source endpoint: loads demo docs (evidence: `web/src/app/page.tsx`)
- Demo source endpoint → Demo API documentation: reads demo docs (evidence: `web/src/app/api/audit-source/route.ts`)
- Audit endpoint → Repository discovery: discovers files (evidence: `web/src/app/api/audit/route.ts`)
- Repository discovery → GitHub: requests tree (evidence: `web/src/app/api/audit/route.ts`)
- Audit endpoint → Selected file fetch: fetches selected files (evidence: `web/src/app/api/audit/route.ts`)
- Selected file fetch → GitHub: fetches file content (evidence: `web/src/app/api/audit/route.ts`)
- Audit endpoint → Documentation extraction: extracts documentation (evidence: `web/src/app/api/audit/route.ts`)
- Audit endpoint → Source extraction: extracts implementation (evidence: `web/src/app/api/audit/route.ts`)
- Documentation extraction → Groq fallback: uses prose fallback (evidence: `web/src/lib/docExtractor.ts`)
- Source extraction → Groq fallback: uses targeted fallback (evidence: `web/src/lib/codeExtractor.ts`)
- Documentation extraction → Normalized contracts: produces contracts (evidence: `web/src/types/contract.ts`)
- Source extraction → Normalized contracts: produces contracts (evidence: `web/src/types/contract.ts`)
- Audit endpoint → Deterministic drift engine: compares contracts (evidence: `README.md`)
- Deterministic drift engine → Provenanced findings: reports drift (evidence: `web/src/lib/driftEngine.ts`)
- Audit endpoint → Provenanced findings: returns audit report (evidence: `README.md`)
- Provenanced findings → Findings and map: displays evidence (evidence: `README.md`)
- Findings and map → Audit UI: renders in (evidence: `web/src/app/page.tsx`)
- Audit UI → Patch and diff engine: applies patches (evidence: `web/src/app/page.tsx`)
- Audit UI → Audit endpoint: submits re-audit (evidence: `web/src/app/page.tsx`)
- Demo auth handlers → Provenanced findings: supplies implementation evidence (evidence: `README.md`)
- Demo API documentation → Provenanced findings: supplies documentation evidence (evidence: `README.md`)
