# jamietso/tabular_review architecture

> Architecture diagram of the GitHub repository jamietso/tabular_review, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamietso/tabular_review
- Repository: https://github.com/jamietso/tabular_review

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered web application ("Tabular Review for Bulk Document Analysis") that lets legal professionals upload large volumes of contracts, automatically extract structured data, inspect source citations, and interact via a spreadsheet UI and chat analyst.
- Frontend: React + TypeScript + Tailwind CSS (Vite-bundled).
- Backend: A Python microservice (“Docling”) for high-fidelity PDF/DOCX → Markdown conversion.
- AI Integration: Google Gemini via GenAI SDK (Gemini 2.5 Pro / 3.0 Pro).

##### File Structure Analysis
- Top-Level Files / Configs:
– vite.config.ts, tsconfig.json, package.json, pnpm-lock.yaml → frontend build & TypeScript config
– .env.example → placeholder for VITE_GEMINI_API_KEY
- Directories:
– services/ → client-side logic calling AI and data-processing endpoints (geminiService.ts, documentProcessor.ts)
– utils/ → sampleData.ts (for mocking), types.ts (shared TypeScript types)
– server/ → Python Docling service (main.py + requirements.txt)
- Key Patterns:
– UI layer (React) ←→ Service layer (services/*.ts) ←→ External endpoints (Python backend + Google Gemini API)
– No persistent database – state is managed in UI (client state) and transiently in the Python service.

##### README Insights
- Describes AI-powered extraction, dynamic schema, verification & citations, spreadsheet interface, integrated chat.
- Specifies two backends: local Docling (server/main.py) and Google Gemini (external AI service).
- No mention of persistent storage – assumes ephemeral processing.

##### Blueprint
a. Main Components
1. Client Browser (React App)
2. Frontend Layers:
– Presentation Components (components/*)
– Service Layer (services/documentProcessor.ts, services/geminiService.ts)
3. Local Conversion Service (Python Docling microservice)
4. External AI Service (Google Gemini via HTTPS)
5. (Optional) In-memory or browser storage for session data
b. Relationships & Data Flows
1. User → React UI (upload PDF/DOCX)
2. React → POST to Docling service → Markdown text returned
3. React → Call Google Gemini API via geminiService → JSON extraction (clauses, dates, entities)
4. React state updated → DataGrid renders structured table
5. On cell click → React fetches citation location from original Markdown / PDF via documentProcessor
6. Chat Interface: React → Gemini API (with contextual prompt intersecting full dataset) → display answers
c. Architectural Patterns & Design Principles
– Component-based UI: single responsibility for each React component
– Service abstraction: keep AI & conversion logic out of UI components
– Microservice for document conversion decouples heavy PDF parsing from frontend
– Stateless backend: no persistence, scales horizontally if needed
d. Key Technologies/Frameworks
– Frontend: React 19, TypeScript, Tailwind CSS, Vite
– Backend: Python 3.x, Docling library
– AI: Google GenAI SDK (Gemini 2.5 / 3.0 Pro)
– Packaging: pnpm, pip + venv

## Diagram (Mermaid)

```mermaid
graph TD
    %% Web Client Layer
    subgraph "Web Client"
        subgraph "Entry Point"
            App["App.tsx"]:::frontend
            IndexTS["index.tsx"]:::frontend
            IndexHTML["index.html"]:::frontend
        end
        subgraph "Presentation Components"
            AddColumn["AddColumnMenu.tsx"]:::frontend
            ChatIntf["ChatInterface.tsx"]:::frontend
            DataGrid["DataGrid.tsx"]:::frontend
            DocUpload["DocumentUpload.tsx"]:::frontend
            Verification["VerificationSidebar.tsx"]:::frontend
            Icons["Icons.tsx"]:::frontend
        end
        subgraph "Service Layer"
            DocProc["documentProcessor.ts"]:::service
            GeminiSvc["geminiService.ts"]:::service
        end
        subgraph "Utils & Types"
            Types["types.ts"]:::service
            SampleData["sampleData.ts"]:::service
        end
        subgraph "Build & Config"
            ViteConfig["vite.config.ts"]:::service
            TsConfig["tsconfig.json"]:::service
            Package["package.json"]:::service
            Pnpm["pnpm-lock.yaml"]:::service
            Env[".env.example"]:::service
        end
    end

    %% Backend Microservices
    subgraph "Backend Microservices"
        Docling["Docling Conversion Service\n(server/main.py)"]:::microservice
    end

    %% External Services
    subgraph "External Services"
        GeminiAPI["Google Gemini API"]:::external
    end

    %% User Interaction
    User["User"]:::external -->|"interacts with"| IndexHTML

    %% Frontend Component Flows
    IndexHTML --> App
    App --> AddColumn
    App --> ChatIntf
    App --> DataGrid
    App --> DocUpload
    App --> Verification
    App --> Icons

    %% Document Upload & Conversion Pipeline
    DocUpload -->|"upload file"| DocProc
    DocProc -->|"POST /convert"| Docling
    Docling -->|"Markdown text"| DocProc
    DocProc --> App

    %% AI Extraction Pipeline
    App --> GeminiSvc
    ChatIntf -->|"query context"| GeminiSvc
    GeminiSvc -->|"GenAI SDK call"| GeminiAPI
    GeminiAPI -->|"extracted JSON"| GeminiSvc
    GeminiSvc --> App
    App --> DataGrid

    %% Citation Lookup Interaction
    DataGrid -.->|"click cell lookup"| DocProc

    %% Click Events
    click App "https://github.com/jamietso/tabular_review/blob/main/App.tsx"
    click IndexTS "https://github.com/jamietso/tabular_review/blob/main/index.tsx"
    click IndexHTML "https://github.com/jamietso/tabular_review/blob/main/index.html"
    click AddColumn "https://github.com/jamietso/tabular_review/blob/main/components/AddColumnMenu.tsx"
    click ChatIntf "https://github.com/jamietso/tabular_review/blob/main/components/ChatInterface.tsx"
    click DataGrid "https://github.com/jamietso/tabular_review/blob/main/components/DataGrid.tsx"
    click DocUpload "https://github.com/jamietso/tabular_review/blob/main/components/DocumentUpload.tsx"
    click Verification "https://github.com/jamietso/tabular_review/blob/main/components/VerificationSidebar.tsx"
    click Icons "https://github.com/jamietso/tabular_review/blob/main/components/Icons.tsx"
    click DocProc "https://github.com/jamietso/tabular_review/blob/main/services/documentProcessor.ts"
    click GeminiSvc "https://github.com/jamietso/tabular_review/blob/main/services/geminiService.ts"
    click Docling "https://github.com/jamietso/tabular_review/blob/main/server/main.py"
    click Env "https://github.com/jamietso/tabular_review/blob/main/.env.example"
    click Types "https://github.com/jamietso/tabular_review/blob/main/types.ts"
    click SampleData "https://github.com/jamietso/tabular_review/blob/main/utils/sampleData.ts"
    click ViteConfig "https://github.com/jamietso/tabular_review/blob/main/vite.config.ts"
    click TsConfig "https://github.com/jamietso/tabular_review/blob/main/tsconfig.json"
    click Package "https://github.com/jamietso/tabular_review/blob/main/package.json"
    click Pnpm "https://github.com/jamietso/tabular_review/blob/main/pnpm-lock.yaml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef service fill:#FFA500,stroke:#000,stroke-width:1px
    classDef microservice fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px
```
