# jatin-05/lexgraph architecture

> Architecture diagram of the GitHub repository jatin-05/lexgraph, 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/jatin-05/lexgraph
- Repository: https://github.com/jatin-05/lexgraph

## Overview

This is a research-oriented contract intelligence API. Its principal workflow accepts a contract, converts it into cached chunks with document structure and provenance, extracts parties and contractual facts per chunk, validates those facts deterministically, and assembles a contract representation. The API also exposes legacy PDF parsing/section-building debug routes and a Docling inspection route. The README describes reference resolution and structure-aware retrieval/question answering as future work; those are shown as planned, not established runtime stages. Relationships are limited to calls shown in excerpts or flows explicitly documented in the README.

Main entry points: [`apps/api/app/services/processing/pipeline.py`](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/processing/pipeline.py) (Processing pipeline), [`apps/api/app/main.py`](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/main.py) (FastAPI routes), [`apps/api/app/services/extraction/extractor.py`](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/extraction/extractor.py) (Semantic extractor), [`apps/api/app/services/parsing/document_parser.py`](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/parsing/document_parser.py) (PDF parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and configuration"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_settings["App settings<br/>[config.py]"]
  node_supabase["Supabase client<br/>[supabase.py]"]
end

subgraph group_document["Document ingestion"]
  node_docling["Docling conversion<br/>[converter.py]"]
  node_pdfparser["PDF parser<br/>[document_parser.py]"]
  node_legacysections["Legacy section builder"]
end

subgraph group_intelligence["Contract intelligence"]
  node_pipeline["Processing pipeline<br/>[pipeline.py]"]
  node_structurebuilder["Structure builder<br/>[builder.py]"]
  node_extractor["Semantic extractor<br/>[extractor.py]"]
  node_validator["Semantic validator"]
end

subgraph group_representation["Models and representation"]
  node_docmodels["Canonical document models<br/>[document.py]"]
  node_structuremodels["Structure models<br/>[models.py]"]
  node_extractionmodels["Extraction models<br/>[models.py]"]
  node_validationmodels["Validation models<br/>[models.py]"]
  node_processingmodels["Processing models<br/>[models.py]"]
  node_contractschema["Contract schema<br/>[schema.py]"]
end

subgraph group_future["Planned capabilities"]
  node_resolver["Reference resolver<br/>[resolver.py]"]
  node_retrieval["Structure-aware retrieval"]
  node_qa["Evidence-backed Q&amp;A"]
end

node_user(("Contract user"))
node_ollama["Local Ollama model"]

node_user -->|"uploads contract"| node_api
node_api -->|"processes contract"| node_pipeline
node_api -->|"parses PDF"| node_pdfparser
node_api -->|"builds sections"| node_legacysections
node_api -->|"inspects conversion"| node_docling
node_api -->|"loads settings"| node_settings
node_api -->|"checks client"| node_supabase
node_pdfparser -->|"returns document"| node_docmodels
node_legacysections -->|"reads pages"| node_docmodels
node_pipeline -->|"converts and chunks"| node_docling
node_pipeline -->|"builds structure"| node_structurebuilder
node_pipeline -->|"extracts chunk facts"| node_extractor
node_extractor -->|"loads model settings"| node_settings
node_extractor -->|"requests extraction"| node_ollama
node_pipeline -->|"validates extraction"| node_validator
node_validator -->|"checks extracted facts"| node_extractionmodels
node_structurebuilder -->|"builds structure data"| node_structuremodels
node_pipeline -->|"assembles representation"| node_processingmodels
node_pipeline -.->|"returns contract schema"| node_contractschema
node_pipeline -->|"returns validation report"| node_validationmodels
node_resolver -.->|"enables resolution-aware retrieval"| node_retrieval
node_retrieval -.->|"supports evidence-backed answers"| node_qa

click node_api "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/main.py"
click node_settings "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/config.py"
click node_supabase "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/db/supabase.py"
click node_docling "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/document/converter.py"
click node_pdfparser "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/parsing/document_parser.py"
click node_legacysections "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/structure/clause_segmenter.py"
click node_pipeline "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/processing/pipeline.py"
click node_structurebuilder "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/structure/builder.py"
click node_extractor "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/extraction/extractor.py"
click node_validator "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/validation/semantic_validator.py"
click node_docmodels "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/models/document.py"
click node_structuremodels "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/structure/models.py"
click node_extractionmodels "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/extraction/models.py"
click node_validationmodels "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/validation/models.py"
click node_processingmodels "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/processing/models.py"
click node_contractschema "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/contract/schema.py"
click node_resolver "https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/reationships/resolver.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_api,node_settings,node_supabase,node_user toneBlue
class node_docling,node_pdfparser,node_legacysections toneAmber
class node_pipeline,node_structurebuilder,node_extractor,node_validator toneMint
class node_docmodels,node_structuremodels,node_extractionmodels,node_validationmodels,node_processingmodels,node_contractschema toneRose
class node_resolver,node_retrieval,node_qa,node_ollama toneIndigo
```

## Components

### API and configuration

- [FastAPI routes](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [App settings](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/config.py): `apps/api/app/config.py`
- [Supabase client](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/db/supabase.py): `apps/api/app/db/supabase.py`

### Document ingestion

- [Docling conversion](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/document/converter.py): `apps/api/app/services/document/converter.py`
- [PDF parser](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/parsing/document_parser.py): `apps/api/app/services/parsing/document_parser.py`
- [Legacy section builder](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/structure/clause_segmenter.py): `apps/api/app/services/structure/clause_segmenter.py`

### Contract intelligence

- [Processing pipeline](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/processing/pipeline.py): `apps/api/app/services/processing/pipeline.py`
- [Structure builder](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/structure/builder.py): `apps/api/app/services/structure/builder.py`
- [Semantic extractor](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/extraction/extractor.py): `apps/api/app/services/extraction/extractor.py`
- [Semantic validator](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/validation/semantic_validator.py): `apps/api/app/services/validation/semantic_validator.py`

### Models and representation

- [Canonical document models](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/models/document.py): `apps/api/app/models/document.py`
- [Structure models](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/structure/models.py): `apps/api/app/services/structure/models.py`
- [Extraction models](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/extraction/models.py): `apps/api/app/services/extraction/models.py`
- [Validation models](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/validation/models.py): `apps/api/app/services/validation/models.py`
- [Processing models](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/processing/models.py): `apps/api/app/services/processing/models.py`
- [Contract schema](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/contract/schema.py): `apps/api/app/services/contract/schema.py`

### Planned capabilities

- [Reference resolver](https://github.com/jatin-05/lexgraph/blob/main/apps/api/app/services/reationships/resolver.py): `apps/api/app/services/reationships/resolver.py`
- **Structure-aware retrieval**
- **Evidence-backed Q&A**

### Other components

- **Contract user**
- **Local Ollama model**

## Connections

- Contract user → FastAPI routes: uploads contract (evidence: `apps/api/app/main.py`)
- FastAPI routes → Processing pipeline: processes contract (evidence: `apps/api/app/main.py`)
- FastAPI routes → PDF parser: parses PDF (evidence: `apps/api/app/main.py`)
- FastAPI routes → Legacy section builder: builds sections (evidence: `apps/api/app/main.py`)
- FastAPI routes → Docling conversion: inspects conversion (evidence: `apps/api/app/main.py`)
- FastAPI routes → App settings: loads settings (evidence: `apps/api/app/main.py`)
- FastAPI routes → Supabase client: checks client (evidence: `apps/api/app/main.py`)
- PDF parser → Canonical document models: returns document (evidence: `apps/api/app/services/parsing/document_parser.py`)
- Legacy section builder → Canonical document models: reads pages (evidence: `apps/api/app/services/structure/clause_segmenter.py`)
- Processing pipeline → Docling conversion: converts and chunks (evidence: `README.md`)
- Processing pipeline → Structure builder: builds structure (evidence: `apps/api/app/services/processing/pipeline.py`)
- Processing pipeline → Semantic extractor: extracts chunk facts (evidence: `apps/api/app/services/processing/pipeline.py`)
- Semantic extractor → App settings: loads model settings (evidence: `apps/api/app/services/extraction/extractor.py`)
- Semantic extractor → Local Ollama model: requests extraction (evidence: `README.md`)
- Processing pipeline → Semantic validator: validates extraction (evidence: `apps/api/app/services/processing/pipeline.py`)
- Semantic validator → Extraction models: checks extracted facts (evidence: `apps/api/app/services/validation/semantic_validator.py`)
- Structure builder → Structure models: builds structure data (evidence: `apps/api/app/services/structure/builder.py`)
- Processing pipeline → Processing models: assembles representation (evidence: `apps/api/app/services/processing/pipeline.py`)
- Processing pipeline → Contract schema: returns contract schema
- Processing pipeline → Validation models: returns validation report (evidence: `apps/api/app/services/processing/pipeline.py`)
- Reference resolver → Structure-aware retrieval: enables resolution-aware retrieval (evidence: `README.md`)
- Structure-aware retrieval → Evidence-backed Q&A: supports evidence-backed answers (evidence: `README.md`)
