# ashuradhipathi/ai-contract-assistant architecture

> Architecture diagram of the GitHub repository ashuradhipathi/ai-contract-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashuradhipathi/ai-contract-assistant
- Repository: https://github.com/ashuradhipathi/ai-contract-assistant

## Overview

##### Project Type and Purpose
- This is a single‑repo, full‑stack Python application built on Streamlit.
- Purpose: ingest uploaded contract files, extract clauses and insights, generate deviations against templates, and present results in a multi‑page UI.

##### File Structure
- Top level:
- New_Contract.py: entry point (Streamlit app)
- rag.py: functions to generate embeddings and manage vector store (RAG)
- utils.py: text‑extraction and NLP helper functions (extract_clauses, extract_keypoints, find_deviations)
- requirements.txt: dependencies (streamlit, openai, langchain, vector‑db, etc.)
- Documentation.md/README.md: high‑level overview and setup
- pages/ directory:
- Clauses.py, Contract_Insights.py, Deviations.py — each implements a Streamlit page using utility functions.

##### Extract Insights from the README
- The app uses Streamlit to render a multi‑page interface.
- It relies on helper functions in utils.py and on a retrieval‑augmented generation approach implemented in rag.py.
- Key workflows: file upload → text extraction → embedding / vector‑store build or query → LLM call → render results.

##### Main Components
a. Frontend/UI Layer
- Streamlit app (New_Contract.py + pages/*.py)
- Pages: Home (upload), Clauses, Contract Insights, Deviations
b. Application/Business‑Logic Layer
- utils.py: text preprocessing, clause/keypoint/deviation extraction
- rag.py: embedding generation, vector‑store creation & querying
c. Data/Storage Layer
- Local file store for uploaded contracts (could be ephemeral)
- Vector database (e.g., Chroma or FAISS instance)
d. External Services
- OpenAI (LLM API for generation & embeddings)
- Any OCR/PDF‑parsing library (if used for text extraction)

##### Relationships & Data Flows
- User interacts with Streamlit UI → uploads contract file.
- UI calls utils.extract_text() → raw contract text.
- Raw text passed to rag.create_vectorstore() → embeds via OpenAI → stored in vector DB.
- On each page:
- “Clauses” page calls utils.extract_clauses(text) → may query vector store + LLM.
- “Contract Insights” page calls utils.extract_keypoints(text).
- “Deviations” page calls utils.find_deviations(text, template).
- Results returned to UI and displayed.

##### Architectural Patterns & Design Principles
- Modular separation: UI (pages) vs. business logic (utils, rag).
- RAG pattern: embeddings + vector‑store retrieval + LLM generation.
- Single‑process monolith (Streamlit).
- Utility functions centralized in utils.py for reusability.

##### Detailed Element Checklist
- Labels: function names (extract_text, create_vectorstore, extract_clauses, etc.)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "UI Layer"
        A["Streamlit App\n(New_Contract.py)"]:::ui
        B["Clauses Page\n(pages/Clauses.py)"]:::ui
        C["Contract Insights\n(pages/Contract_Insights.py)"]:::ui
        D["Deviations Page\n(pages/Deviations.py)"]:::ui
    end

    subgraph "Business Logic Layer"
        E["Utils\n(utils.py)"]:::logic
        F["RAG Module\n(rag.py)"]:::logic
    end

    subgraph "Data & External Layer"
        G["Local File Store"]:::storage
        H["Vector DB"]:::storage
        I["OpenAI API"]:::external
        J["OCR/PDF Parser"]:::external
    end

    subgraph "Project Files"
        K["requirements.txt"]:::meta
        L["Documentation.md"]:::meta
        M["README.md"]:::meta
    end

    A -->|"upload contract"| G
    A -->|"call extract_text()"| E
    E -->|"text output"| F
    F -->|"embed(text)"| I
    F -->|"store embeddings"| H

    B -->|"call extract_clauses()"| E
    C -->|"call extract_keypoints()"| E
    D -->|"call find_deviations()"| E

    B -->|"query embeddings"| H
    H -->|"retrieved vectors"| F
    F -->|"LLM generate"| I
    I -->|"LLM response"| F
    F -->|"results"| E

    E -->|"return results"| B
    E -->|"return results"| C
    E -->|"return results"| D
    E -->|"return processing results"| A

    classDef ui fill:#E8F0FE,stroke:#0366d6;
    classDef logic fill:#FFF4E5,stroke:#d29922;
    classDef storage fill:#E8F5E9,stroke:#2E7D32;
    classDef external fill:#FBE9E7,stroke:#D84315;
    classDef meta fill:#F3E5F5,stroke:#6A1B9A;

    click A "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/New_Contract.py"
    click B "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/pages/Clauses.py"
    click C "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/pages/Contract_Insights.py"
    click D "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/pages/Deviations.py"
    click E "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/utils.py"
    click F "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/rag.py"
    click K "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/requirements.txt"
    click L "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/Documentation.md"
    click M "https://github.com/ashuradhipathi/ai-contract-assistant/blob/main/README.md"
```
