# yashwaghh/ai_legal_help architecture

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

- Interactive diagram: https://gitdiagram.com/yashwaghh/ai_legal_help
- Repository: https://github.com/yashwaghh/ai_legal_help

## Overview

ClearClause is a browser-based legal-information assistant for text-based PDFs. Its main workflow is to upload a PDF for a plain-language briefing or document-grounded question, or upload two versions for a deterministic diff followed by an AI explanation; results include checked citations and can be downloaded. FastAPI routes coordinate extraction and analysis. In public mode, middleware verifies account and app credentials and reserves weighted quotas before protected requests proceed. The README documents Firebase, Firestore, and Vertex AI integrations; source excerpts do not expose every internal implementation detail.

Main entry points: [`app/main.py`](https://github.com/yashwaghh/ai_legal_help/blob/main/app/main.py) (API routes), [`app/static/app.js`](https://github.com/yashwaghh/ai_legal_help/blob/main/app/static/app.js) (Web interface), [`app/security.py`](https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.py) (Request middleware), [`app/ai.py`](https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py) (Briefing generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_web_ui["Web interface<br/>[app.js]"]
  node_page_template["Page template<br/>[index.html]"]
end

subgraph group_api["API and documents"]
  node_api_routes["API routes<br/>[main.py]"]
  node_pdf_extraction["PDF extraction<br/>[documents.py]"]
  node_response_schemas["Response schemas<br/>[schemas.py]"]
end

subgraph group_analysis["Analysis"]
  node_briefing["Briefing generation<br/>[ai.py]"]
  node_question_answering["Grounded Q&amp;A<br/>[ai.py]"]
  node_version_comparison["Version comparison<br/>[ai.py]"]
  node_citation_checks["Citation validation<br/>[documents.py]"]
end

subgraph group_security["Request security"]
  node_request_middleware["Request middleware<br/>[security.py]"]
  node_identity_verification["Identity verification<br/>[security.py]"]
  node_quota_reservation["Quota reservation<br/>[security.py]"]
end

node_user(("User"))
node_vertex_ai["Gemini on Vertex AI"]
node_firebase_auth["Firebase Authentication"]
node_app_check["Firebase App Check"]
node_firestore[("Quota records")]

node_user -->|"uses"| node_web_ui
node_web_ui -->|"loads page"| node_page_template
node_web_ui -->|"uploads and queries"| node_api_routes
node_api_routes -->|"serves"| node_page_template
node_request_middleware -->|"guards requests"| node_api_routes
node_request_middleware -->|"checks credentials"| node_identity_verification
node_identity_verification -->|"verifies ID token"| node_firebase_auth
node_request_middleware -.->|"verifies app token"| node_app_check
node_request_middleware -->|"reserves units"| node_quota_reservation
node_quota_reservation -->|"reads and writes"| node_firestore
node_quota_reservation -->|"persists quota events"| node_firestore
node_api_routes -->|"extracts PDF text"| node_pdf_extraction
node_api_routes -->|"requests briefing"| node_briefing
node_api_routes -->|"requests answer"| node_question_answering
node_api_routes -->|"requests comparison"| node_version_comparison
node_briefing -->|"generates findings"| node_vertex_ai
node_question_answering -->|"generates answer"| node_vertex_ai
node_version_comparison -->|"summarizes diff"| node_vertex_ai
node_briefing -->|"checks citations"| node_citation_checks
node_question_answering -->|"checks citations"| node_citation_checks
node_version_comparison -->|"checks citations"| node_citation_checks
node_briefing -->|"validates response"| node_response_schemas
node_question_answering -->|"validates response"| node_response_schemas
node_version_comparison -->|"validates response"| node_response_schemas
node_api_routes -->|"returns typed results"| node_response_schemas
node_web_ui -->|"signs in users"| node_firebase_auth
node_web_ui -.->|"obtains app token"| node_app_check

click node_web_ui "https://github.com/yashwaghh/ai_legal_help/blob/main/app/static/app.js"
click node_page_template "https://github.com/yashwaghh/ai_legal_help/blob/main/app/templates/index.html"
click node_api_routes "https://github.com/yashwaghh/ai_legal_help/blob/main/app/main.py"
click node_pdf_extraction "https://github.com/yashwaghh/ai_legal_help/blob/main/app/documents.py"
click node_response_schemas "https://github.com/yashwaghh/ai_legal_help/blob/main/app/schemas.py"
click node_briefing "https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py"
click node_question_answering "https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py"
click node_version_comparison "https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py"
click node_citation_checks "https://github.com/yashwaghh/ai_legal_help/blob/main/app/documents.py"
click node_request_middleware "https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.py"
click node_identity_verification "https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.py"
click node_quota_reservation "https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.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_web_ui,node_page_template,node_user toneBlue
class node_api_routes,node_pdf_extraction,node_response_schemas,node_firestore toneAmber
class node_briefing,node_question_answering,node_version_comparison,node_citation_checks toneMint
class node_request_middleware,node_identity_verification,node_quota_reservation toneRose
class node_vertex_ai,node_firebase_auth,node_app_check toneIndigo
```

## Components

### Browser experience

- [Web interface](https://github.com/yashwaghh/ai_legal_help/blob/main/app/static/app.js): `app/static/app.js`
- [Page template](https://github.com/yashwaghh/ai_legal_help/blob/main/app/templates/index.html): `app/templates/index.html`

### API and documents

- [API routes](https://github.com/yashwaghh/ai_legal_help/blob/main/app/main.py): `app/main.py`
- [PDF extraction](https://github.com/yashwaghh/ai_legal_help/blob/main/app/documents.py): `app/documents.py`
- [Response schemas](https://github.com/yashwaghh/ai_legal_help/blob/main/app/schemas.py): `app/schemas.py`

### Analysis

- [Briefing generation](https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py): `app/ai.py`
- [Grounded Q&A](https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py): `app/ai.py`
- [Version comparison](https://github.com/yashwaghh/ai_legal_help/blob/main/app/ai.py): `app/ai.py`
- [Citation validation](https://github.com/yashwaghh/ai_legal_help/blob/main/app/documents.py): `app/documents.py`

### Request security

- [Request middleware](https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.py): `app/security.py`
- [Identity verification](https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.py): `app/security.py`
- [Quota reservation](https://github.com/yashwaghh/ai_legal_help/blob/main/app/security.py): `app/security.py`

### Other components

- **User**
- **Gemini on Vertex AI**
- **Firebase Authentication**
- **Firebase App Check**
- **Quota records**

## Connections

- User → Web interface: uses
- Web interface → Page template: loads page
- Web interface → API routes: uploads and queries
- API routes → Page template: serves
- Request middleware → API routes: guards requests
- Request middleware → Identity verification: checks credentials
- Identity verification → Firebase Authentication: verifies ID token
- Request middleware → Firebase App Check: verifies app token
- Request middleware → Quota reservation: reserves units
- Quota reservation → Quota records: reads and writes
- Quota reservation → Quota records: persists quota events
- API routes → PDF extraction: extracts PDF text
- API routes → Briefing generation: requests briefing
- API routes → Grounded Q&A: requests answer
- API routes → Version comparison: requests comparison
- Briefing generation → Gemini on Vertex AI: generates findings
- Grounded Q&A → Gemini on Vertex AI: generates answer
- Version comparison → Gemini on Vertex AI: summarizes diff
- Briefing generation → Citation validation: checks citations
- Grounded Q&A → Citation validation: checks citations
- Version comparison → Citation validation: checks citations
- Briefing generation → Response schemas: validates response
- Grounded Q&A → Response schemas: validates response
- Version comparison → Response schemas: validates response
- API routes → Response schemas: returns typed results
- Web interface → Firebase Authentication: signs in users
- Web interface → Firebase App Check: obtains app token