# vaibhavghugretkar/kairos architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhavghugretkar/kairos
- Repository: https://github.com/vaibhavghugretkar/kairos

## Overview

##### Project type and purpose
- LexiClarus is a full-stack AI-powered legal-assistant web application.
- Purpose: Upload a PDF/DOCX contract, extract and simplify legal clauses, flag risks, and answer user questions via a web UI.

##### File structure
- Top-level files:
- main.py      → FastAPI app entrypoint
- app.py       → Streamlit frontend entrypoint
- agents.py    → Defines the four modular “agents” (Extractor, Simplifier, Risk Identifier, QA Agent)
- download_model.py → Helper to fetch or cache local models
- requirements.txt → Python dependencies
- assets/      → Static images & screenshots used in README and UI
- No separate “frontend” or “backend” folders, but code clearly splits UI (app.py) and API (main.py).

##### README for architectural insights
- 4 modular agents running in a pipeline
- Backend built on FastAPI + Uvicorn
- Frontend built on Streamlit
- Core models:
- Flan-T5 (local, CPU)
- Fine-tuned Gemma (hosted on Hugging Face Space)
- Gemini 2.0 Flash (Google API with heuristic fallback)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Layer"
        UI["Streamlit Frontend\n(app.py)"]:::frontend
    end

    subgraph "Backend Layer"
        API["FastAPI Backend\n(main.py)"]:::backend
        Fetcher["Model Fetcher\n(download_model.py)"]:::utility

        subgraph "Agents Pipeline"
            Extractor["Clause Extractor\n(Flan-T5)\n(agents.py)"]:::agent
            Simplifier["Text Simplifier\n(Gemma on HF Space)\n(agents.py)"]:::agent
            Risk["Risk Identifier\n(Gemini + Heuristics)\n(agents.py)"]:::agent
            QA["QA Agent\n(Gemini + Fallback)\n(agents.py)"]:::agent
        end

        Docs["Dependency Definitions\n(requirements.txt)"]:::docs
        Overview["Project Overview\n(README.md)"]:::docs
        Assets["Static Assets\n(assets/)"]:::static
        Screenshots["Sample Diagrams\n(assets/screenshots/)"]:::static
    end

    subgraph "External Services"
        HF["Hugging Face Spaces API"]:::external
        Gemini["Google Gemini API"]:::external
    end

    UI -->|"Upload PDF/DOCX"| API
    API -->|"Load models"| Fetcher
    Fetcher -->|"Models available"| Extractor
    Extractor -->|"Clauses JSON"| Simplifier
    Simplifier -->|"Simplified Text"| Risk
    Risk -->|"Risk Flags"| QA
    QA -->|"Answers JSON"| API
    API -->|"Return JSON"| UI

    Simplifier -->|"Simplify Request"| HF
    Risk -->|"Risk Analysis Request"| Gemini
    QA -->|"QA Request"| Gemini

    click UI "https://github.com/vaibhavghugretkar/kairos/blob/main/app.py"
    click API "https://github.com/vaibhavghugretkar/kairos/blob/main/main.py"
    click Fetcher "https://github.com/vaibhavghugretkar/kairos/blob/main/download_model.py"
    click Extractor "https://github.com/vaibhavghugretkar/kairos/blob/main/agents.py"
    click Simplifier "https://github.com/vaibhavghugretkar/kairos/blob/main/agents.py"
    click Risk "https://github.com/vaibhavghugretkar/kairos/blob/main/agents.py"
    click QA "https://github.com/vaibhavghugretkar/kairos/blob/main/agents.py"
    click Assets "https://github.com/vaibhavghugretkar/kairos/tree/main/assets/"
    click Screenshots "https://github.com/vaibhavghugretkar/kairos/tree/main/assets/screenshots/"
    click Docs "https://github.com/vaibhavghugretkar/kairos/blob/main/requirements.txt"
    click Overview "https://github.com/vaibhavghugretkar/kairos/blob/main/README.md"

    classDef frontend fill:#D6E9FE,stroke:#4A90E2,color:#000
    classDef backend fill:#E8F5E9,stroke:#43A047,color:#000
    classDef utility fill:#F3E5F5,stroke:#8E24AA,color:#000
    classDef agent fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#000
    classDef docs fill:#FCE4EC,stroke:#EC407A,color:#000
    classDef static fill:#FFF9C4,stroke:#FBC02D,color:#000
```
