# aashik1701/fact-layer architecture

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

- Interactive diagram: https://gitdiagram.com/aashik1701/fact-layer
- Repository: https://github.com/aashik1701/fact-layer

## Overview

Fact Layer extracts evidence-grounded, qualifier-rich facts from PDFs, then finds cross-document candidates and compares them only after a deterministic comparability gate. Its workflow spans parsing and triage, extraction and verification, normalization and resolution, storage and retrieval, then relational adjudication and API/UI inspection. The README documents additional graph, lineage, temporal, investigation, and diagnostics capabilities; their internal wiring is not fully shown in the sampled source, so those links are omitted. The frontend and some pipeline relationships are represented from README statements and import references rather than complete implementation excerpts.

Main entry points: [`api.py`](https://github.com/aashik1701/fact-layer/blob/main/api.py) (FastAPI service), [`fact_layer/extract.py`](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/extract.py) (Fact extraction), [`frontend/src/lib/api.ts`](https://github.com/aashik1701/fact-layer/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/aashik1701/fact-layer/blob/main/frontend/src/App.tsx) (Fact Layer UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_app["Fact Layer UI<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_review_ui["Fact and relation review"]
  node_evidence_ui["Evidence viewer<br/>[EvidenceModal.tsx]"]
end

subgraph group_service["Service layer"]
  node_http["FastAPI service<br/>[api.py]"]
end

subgraph group_ingest["Fact ingestion"]
  node_parse["PDF parsing<br/>[parse.py]"]
  node_triage["Page triage<br/>[triage.py]"]
  node_extract["Fact extraction<br/>[extract.py]"]
  node_verify["Quote verification<br/>[value_verify.py]"]
  node_normalize["Normalization<br/>[normalize.py]"]
  node_resolve["Canonical resolution<br/>[resolve.py]"]
end

subgraph group_reason["Comparison and retrieval"]
  node_retrieval["Candidate retrieval<br/>[index.py]"]
  node_gate["Comparability gate<br/>[comparability.py]"]
  node_adjudicate["Relation adjudication<br/>[adjudicate.py]"]
  node_graph["Knowledge graph projection<br/>[graph.py]"]
  node_investigate["Comparability investigation<br/>[investigate.py]"]
  node_lineage["Evidence lineage<br/>[lineage.py]"]
  node_temporal["Temporal knowledge<br/>[temporal.py]"]
  node_diagnostics["Pipeline diagnostics<br/>[diagnostics.py]"]
end

subgraph group_persistence["State and evidence"]
  node_models["Fact and evidence model<br/>[models.py]"]
  node_store["Dedup and clustering<br/>[store.py]"]
  node_storage["Fact storage contract<br/>[storage.py]"]
  node_sqlite[("SQLite backend<br/>[sqlite_storage.py]")]
end

node_user(("Analyst"))

node_user -->|"uses"| node_app
node_app -->|"requests data"| node_api_client
node_app -->|"renders"| node_review_ui
node_api_client -->|"calls REST API"| node_http
node_http -->|"starts ingestion"| node_parse
node_parse -->|"feeds pages"| node_triage
node_triage -->|"selects pages"| node_extract
node_extract -->|"verifies spans"| node_verify
node_extract -->|"normalizes values"| node_normalize
node_extract -->|"uses parsed text"| node_parse
node_resolve -->|"uses normalization"| node_normalize
node_store -.->|"adjudicates clusters"| node_adjudicate
node_retrieval -->|"gates candidates"| node_gate
node_gate -->|"supplies verdict"| node_adjudicate
node_http -->|"serves candidate queries"| node_retrieval
node_http -->|"serves fact data"| node_store
node_http -->|"serves graph view"| node_graph
node_http -->|"serves investigations"| node_investigate
node_http -->|"serves lineage"| node_lineage
node_http -->|"serves temporal data"| node_temporal
node_http -->|"serves diagnostics"| node_diagnostics
node_storage -->|"implements contract"| node_sqlite
node_storage -->|"serializes records"| node_models
node_store -.->|"persists snapshot"| node_storage
node_evidence_ui -.->|"loads evidence"| node_api_client
node_review_ui -.->|"loads relations"| node_api_client

click node_app "https://github.com/aashik1701/fact-layer/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/aashik1701/fact-layer/blob/main/frontend/src/lib/api.ts"
click node_review_ui "https://github.com/aashik1701/fact-layer/blob/main/frontend/src/components/relations/RelationInspectorModal.tsx"
click node_evidence_ui "https://github.com/aashik1701/fact-layer/blob/main/frontend/src/components/evidence/EvidenceModal.tsx"
click node_http "https://github.com/aashik1701/fact-layer/blob/main/api.py"
click node_parse "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/parse.py"
click node_triage "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/triage.py"
click node_extract "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/extract.py"
click node_verify "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/value_verify.py"
click node_normalize "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/normalize.py"
click node_resolve "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/resolve.py"
click node_models "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/models.py"
click node_store "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/store.py"
click node_storage "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/storage.py"
click node_sqlite "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/sqlite_storage.py"
click node_retrieval "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/retrieval/index.py"
click node_gate "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/comparability.py"
click node_adjudicate "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/adjudicate.py"
click node_graph "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/graph.py"
click node_investigate "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/investigate.py"
click node_lineage "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/lineage.py"
click node_temporal "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/temporal.py"
click node_diagnostics "https://github.com/aashik1701/fact-layer/blob/main/fact_layer/diagnostics.py"

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_app,node_api_client,node_review_ui,node_evidence_ui toneBlue
class node_http toneAmber
class node_parse,node_triage,node_extract,node_verify,node_normalize,node_resolve toneMint
class node_retrieval,node_gate,node_adjudicate,node_graph,node_investigate,node_lineage,node_temporal,node_diagnostics toneRose
class node_models,node_store,node_storage,node_sqlite,node_user toneIndigo
```

## Components

### User interface

- [Fact Layer UI](https://github.com/aashik1701/fact-layer/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/aashik1701/fact-layer/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Fact and relation review](https://github.com/aashik1701/fact-layer/blob/main/frontend/src/components/relations/RelationInspectorModal.tsx): `frontend/src/components/relations/RelationInspectorModal.tsx`
- [Evidence viewer](https://github.com/aashik1701/fact-layer/blob/main/frontend/src/components/evidence/EvidenceModal.tsx): `frontend/src/components/evidence/EvidenceModal.tsx`

### Service layer

- [FastAPI service](https://github.com/aashik1701/fact-layer/blob/main/api.py): `api.py`

### Fact ingestion

- [PDF parsing](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/parse.py): `fact_layer/parse.py`
- [Page triage](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/triage.py): `fact_layer/triage.py`
- [Fact extraction](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/extract.py): `fact_layer/extract.py`
- [Quote verification](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/value_verify.py): `fact_layer/value_verify.py`
- [Normalization](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/normalize.py): `fact_layer/normalize.py`
- [Canonical resolution](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/resolve.py): `fact_layer/resolve.py`

### Comparison and retrieval

- [Candidate retrieval](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/retrieval/index.py): `fact_layer/retrieval/index.py`
- [Comparability gate](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/comparability.py): `fact_layer/comparability.py`
- [Relation adjudication](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/adjudicate.py): `fact_layer/adjudicate.py`
- [Knowledge graph projection](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/graph.py): `fact_layer/graph.py`
- [Comparability investigation](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/investigate.py): `fact_layer/investigate.py`
- [Evidence lineage](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/lineage.py): `fact_layer/lineage.py`
- [Temporal knowledge](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/temporal.py): `fact_layer/temporal.py`
- [Pipeline diagnostics](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/diagnostics.py): `fact_layer/diagnostics.py`

### State and evidence

- [Fact and evidence model](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/models.py): `fact_layer/models.py`
- [Dedup and clustering](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/store.py): `fact_layer/store.py`
- [Fact storage contract](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/storage.py): `fact_layer/storage.py`
- [SQLite backend](https://github.com/aashik1701/fact-layer/blob/main/fact_layer/sqlite_storage.py): `fact_layer/sqlite_storage.py`

### Other components

- **Analyst**

## Connections

- Analyst → Fact Layer UI: uses (evidence: `README.md`)
- Fact Layer UI → API client: requests data (evidence: `frontend/src/App.tsx`)
- Fact Layer UI → Fact and relation review: renders (evidence: `frontend/src/App.tsx`)
- API client → FastAPI service: calls REST API (evidence: `README.md`)
- FastAPI service → PDF parsing: starts ingestion (evidence: `README.md`)
- PDF parsing → Page triage: feeds pages (evidence: `README.md`)
- Page triage → Fact extraction: selects pages (evidence: `README.md`)
- Fact extraction → Quote verification: verifies spans (evidence: `fact_layer/extract.py`)
- Fact extraction → Normalization: normalizes values (evidence: `fact_layer/extract.py`)
- Fact extraction → PDF parsing: uses parsed text (evidence: `fact_layer/extract.py`)
- Canonical resolution → Normalization: uses normalization (evidence: `fact_layer/resolve.py`)
- Dedup and clustering → Relation adjudication: adjudicates clusters
- Candidate retrieval → Comparability gate: gates candidates (evidence: `fact_layer/retrieval/adaptive.py`)
- Comparability gate → Relation adjudication: supplies verdict (evidence: `fact_layer/adjudicate.py`)
- FastAPI service → Candidate retrieval: serves candidate queries (evidence: `api.py`)
- FastAPI service → Dedup and clustering: serves fact data (evidence: `api.py`)
- FastAPI service → Knowledge graph projection: serves graph view (evidence: `api.py`)
- FastAPI service → Comparability investigation: serves investigations (evidence: `api.py`)
- FastAPI service → Evidence lineage: serves lineage (evidence: `api.py`)
- FastAPI service → Temporal knowledge: serves temporal data (evidence: `api.py`)
- FastAPI service → Pipeline diagnostics: serves diagnostics (evidence: `api.py`)
- Fact storage contract → SQLite backend: implements contract (evidence: `fact_layer/sqlite_storage.py`)
- Fact storage contract → Fact and evidence model: serializes records (evidence: `fact_layer/storage.py`)
- Dedup and clustering → Fact storage contract: persists snapshot
- Evidence viewer → API client: loads evidence
- Fact and relation review → API client: loads relations
