# karankarpe22/terms-of-service-red-flag-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/karankarpe22/terms-of-service-red-flag-scanner
- Repository: https://github.com/karankarpe22/terms-of-service-red-flag-scanner

## Overview

This is a web-based ToS scanner: users submit PDF or pasted text, then receive segmented and categorized clauses, attention flags, cross-clause relationships, and grounded explanations or document Q&A. The API routes orchestrate ingestion and analysis; the browser presents results. Retrieval supports concern-focused queries, and Gemini can provide explanations, with deterministic mock mode also documented. Edges follow the route imports listed in the SOURCE INDEX and explicit README capabilities; unsampled implementation details are not inferred.

Main entry points: [`backend/api/routes.py`](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/api/routes.py) (API routes), [`backend/llm/client.py`](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/llm/client.py) (Explanation and Q&A), [`backend/retrieval/embedder.py`](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/retrieval/embedder.py) (Text embeddings), [`frontend/app.js`](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/frontend/app.js) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_web["Web interface<br/>[app.js]"]
  node_api["API routes<br/>[routes.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_extract["Document extraction<br/>[extractor.py]"]
  node_clean["Text cleaning<br/>[cleaner.py]"]
  node_segment["Clause segmentation<br/>[segmenter.py]"]
  node_docstore[("Document registry<br/>[store.py]")]
end

subgraph group_analysis["Clause analysis"]
  node_classifier["Clause classification<br/>[classifier.py]"]
  node_attention["Attention levels<br/>[attention.py]"]
  node_relationships["Clause relationships<br/>[relationships.py]"]
end

subgraph group_answers["Retrieval and explanations"]
  node_embedder["Text embeddings<br/>[embedder.py]"]
  node_vectorstore[("Clause retrieval<br/>[vector_store.py]")]
  node_llm["Explanation and Q&amp;A<br/>[client.py]"]
  node_validator["Evidence validator<br/>[validator.py]"]
end

node_user(("User"))
node_gemini{{"Google Gemini"}}

node_user -->|"submits document"| node_web
node_web -->|"uses API"| node_api
node_api -->|"extracts text"| node_extract
node_extract -->|"normalizes text"| node_clean
node_api -->|"segments clauses"| node_segment
node_api -->|"stores document"| node_docstore
node_api -->|"classifies clauses"| node_classifier
node_api -->|"assigns attention"| node_attention
node_api -->|"detects relationships"| node_relationships
node_api -->|"indexes and retrieves"| node_vectorstore
node_classifier -->|"embeds categories"| node_embedder
node_relationships -->|"compares semantics"| node_embedder
node_vectorstore -->|"embeds queries"| node_embedder
node_api -->|"requests explanations"| node_llm
node_llm -->|"validates evidence"| node_validator
node_llm -.->|"generates responses"| node_gemini

click node_web "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/frontend/app.js"
click node_api "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/api/routes.py"
click node_extract "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/extractor.py"
click node_clean "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/cleaner.py"
click node_segment "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/segmenter.py"
click node_docstore "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/store.py"
click node_classifier "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/analysis/classifier.py"
click node_attention "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/analysis/attention.py"
click node_relationships "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/analysis/relationships.py"
click node_embedder "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/retrieval/embedder.py"
click node_vectorstore "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/retrieval/vector_store.py"
click node_llm "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/llm/client.py"
click node_validator "https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/llm/validator.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,node_api,node_user toneBlue
class node_extract,node_clean,node_segment,node_docstore toneAmber
class node_classifier,node_attention,node_relationships toneMint
class node_embedder,node_vectorstore,node_llm,node_validator toneRose
class node_gemini toneIndigo
```

## Components

### User interface

- [Web interface](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/frontend/app.js): `frontend/app.js`
- [API routes](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/api/routes.py): `backend/api/routes.py`

### Document ingestion

- [Document extraction](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/extractor.py): `backend/document/extractor.py`
- [Text cleaning](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/cleaner.py): `backend/document/cleaner.py`
- [Clause segmentation](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/segmenter.py): `backend/document/segmenter.py`
- [Document registry](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/document/store.py): `backend/document/store.py`

### Clause analysis

- [Clause classification](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/analysis/classifier.py): `backend/analysis/classifier.py`
- [Attention levels](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/analysis/attention.py): `backend/analysis/attention.py`
- [Clause relationships](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/analysis/relationships.py): `backend/analysis/relationships.py`

### Retrieval and explanations

- [Text embeddings](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/retrieval/embedder.py): `backend/retrieval/embedder.py`
- [Clause retrieval](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/retrieval/vector_store.py): `backend/retrieval/vector_store.py`
- [Explanation and Q&A](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/llm/client.py): `backend/llm/client.py`
- [Evidence validator](https://github.com/karankarpe22/terms-of-service-red-flag-scanner/blob/main/backend/llm/validator.py): `backend/llm/validator.py`

### Other components

- **User**
- **Google Gemini**

## Connections

- User → Web interface: submits document (evidence: `README.md`)
- Web interface → API routes: uses API (evidence: `README.md`)
- API routes → Document extraction: extracts text (evidence: `backend/api/routes.py`)
- Document extraction → Text cleaning: normalizes text (evidence: `backend/document/extractor.py`)
- API routes → Clause segmentation: segments clauses (evidence: `backend/api/routes.py`)
- API routes → Document registry: stores document (evidence: `backend/api/routes.py`)
- API routes → Clause classification: classifies clauses (evidence: `backend/api/routes.py`)
- API routes → Attention levels: assigns attention (evidence: `backend/api/routes.py`)
- API routes → Clause relationships: detects relationships (evidence: `backend/api/routes.py`)
- API routes → Clause retrieval: indexes and retrieves (evidence: `backend/api/routes.py`)
- Clause classification → Text embeddings: embeds categories (evidence: `backend/analysis/classifier.py`)
- Clause relationships → Text embeddings: compares semantics (evidence: `backend/analysis/relationships.py`)
- Clause retrieval → Text embeddings: embeds queries (evidence: `backend/retrieval/vector_store.py`)
- API routes → Explanation and Q&A: requests explanations (evidence: `backend/api/routes.py`)
- Explanation and Q&A → Evidence validator: validates evidence (evidence: `backend/llm/client.py`)
- Explanation and Q&A → Google Gemini: generates responses (evidence: `README.md`)
