# arslaan5/lexiassist architecture

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

- Interactive diagram: https://gitdiagram.com/arslaan5/lexiassist
- Repository: https://github.com/arslaan5/lexiassist

## Overview

##### Project Type and Purpose
- LexiAssist is a full-stack web application (Django-based) with an AI chatbot front end.
- Purpose: Accept user legal queries, convert to embeddings, perform vector search (Pinecone), call an LLM (Groq), and render structured answers.

##### File Structure
- Top level:
- manage.py, requirements.txt
- legal_document_assistant/ – Django project settings, ASGI/WSGI, URLs
- assistant/ – Django app containing models, views, forms, templates, static assets, and data-processing scripts.
- documents/ – Source PDFs ingested into the vector store.
- staticfiles/ & theme/ – Collected static assets (Tailwind, admin, Jazzmin, DRF docs).
- The “assistant/scripts” directory holds the RAG pipeline stages: embedding, ingestion, search, transformation, uploading, and response handling.
- Config files: settings.py (DB, Pinecone, LLM credentials), package.json (static build).

##### README Insights
- Flow: Frontend → backend embedding → Pinecone similarity search → LLM → frontend.
- Tech stack: Django 5.1, Python 3.12, Tailwind CSS, PostgreSQL, Pinecone, langchain, huggingface & Groq APIs.

a. Main Components
- User Browser (React/Tailwind HTML templates)
- Django Server
- URL Router
- Views & Forms (assistant/views.py, forms.py)
- Models (PostgreSQL)
- Scripts Pipeline (assistant/scripts/)
- External Services
- Pinecone Vector DB
- Embedding API (Hugging Face jina-embeddings-v3)
- LLM API (Groq llama-3.1-8b)
- Static Assets Server (collected staticfiles)

b. Relationships & Interactions
1. User submits query → HTTP POST to Django URL endpoint.
2. View invokes data_embedder.py → calls embedding API.
3. embeddings → Pinecone similarity search (data_retriever.py) → returns top chunks.
4. data_transformation.py assembles context → response_handler.py calls LLM API.
5. LLM generates answer → view sends JSON/HTML response.
6. Browser displays answer; user session & auth managed by Django’s auth & assistant/models.py.

c. Architectural Patterns & Principles
- MVC pattern (Django’s MVT)
- Modular pipeline: each script focuses on one step (SRP).
- External service abstraction via utility layer (assistant/scripts/utils.py).

d. Key Technologies
- Django (URLs, Views, Models, Templates)
- Tailwind CSS + Jazzmin (UI)
- PostgreSQL (Django ORM)
- Pinecone & Hugging Face & Groq (external AI services)
- Langchain orchestrator (implicit in scripts)

##### Essential Elements
- Component labels: “User Browser”, “Django (View, Scripts)”, “PostgreSQL”, “Pinecone”, “LLM API”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        Browser["User Browser"]:::frontend
        StaticServer["Static Assets Server"]:::frontend
        Browser -->|"HTTP GET HTML/CSS/JS"| StaticServer
        Browser -->|"HTTP POST /query"| ProjectURLs
    end

    %% Backend Layer
    subgraph "Django Server"
        direction TB
        ASGI["ASGI Entry Point"]:::internal
        WSGI["WSGI Entry Point"]:::internal
        Settings["Settings"]:::internal
        ProjectURLs["Project URL Router"]:::internal
        AppURLs["App URL Router"]:::internal
        Views["Views & Forms"]:::internal
        Models["Django Models (ORM)"]:::internal
        Templates["Templates"]:::frontend

        ProjectURLs -->|routes to| AppURLs
        AppURLs -->|dispatches to| Views
        Views -->|renders| Templates
        Views -->|queries| Models
        Models -->|reads/writes| Postgres
    end

    %% Pipeline Layer
    subgraph "RAG Pipeline" 
        direction TB
        Ingestion["Data Ingestion"]:::pipeline
        Embedder["Embedding Component"]:::pipeline
        Retriever["Retrieval Component"]:::pipeline
        Transformation["Context Assembly"]:::pipeline
        ResponseHandler["LLM Response Handler"]:::pipeline
        Uploader["Vector Store Uploader"]:::pipeline
        Utils["External Service Utilities"]:::pipeline

        Views -->|calls pipeline| Embedder
        Embedder -->|embeddings| Retriever
        Retriever -->|contexts| Transformation
        Transformation -->|prompt| ResponseHandler
        ResponseHandler -->|answer| Views
        Ingestion -->|ingest PDFs| Uploader
        Ingestion -->|uses| Utils
        Embedder -->|uses| Utils
        Retriever -->|uses| Utils
        Transformation -->|uses| Utils
        ResponseHandler -->|uses| Utils
        Uploader -->|uses| Utils
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HFAPI["Hugging Face Embedding API"]:::external
        PineconeDB[(Pinecone Vector DB)]:::db
        LLMAPI["Groq LLM API"]:::external

        Embedder -->|"HTTP POST embeddings"| HFAPI
        Retriever -->|"vector query"| PineconeDB
        Uploader -->|"upload vectors"| PineconeDB
        ResponseHandler -->|"HTTP POST prompt"| LLMAPI
    end

    %% Databases
    subgraph "Databases"
        direction TB
        Postgres[(PostgreSQL DB)]:::db
        Docs["Source Documents (PDFs)"]:::db
        Uploader -->|reads| Docs
    end

    %% Connections back to Browser
    Views -->|"JSON/HTML response"| Browser

    %% Click Events
    click Settings "https://github.com/arslaan5/lexiassist/blob/main/legal_document_assistant/settings.py"
    click ASGI "https://github.com/arslaan5/lexiassist/blob/main/legal_document_assistant/asgi.py"
    click WSGI "https://github.com/arslaan5/lexiassist/blob/main/legal_document_assistant/wsgi.py"
    click ProjectURLs "https://github.com/arslaan5/lexiassist/blob/main/legal_document_assistant/urls.py"
    click AppURLs "https://github.com/arslaan5/lexiassist/blob/main/assistant/urls.py"
    click Models "https://github.com/arslaan5/lexiassist/blob/main/assistant/models.py"
    click Forms "https://github.com/arslaan5/lexiassist/blob/main/assistant/forms.py"
    click Views "https://github.com/arslaan5/lexiassist/blob/main/assistant/views.py"
    click Templates "https://github.com/arslaan5/lexiassist/blob/main/assistant/templates/home.html"
    click Templates "https://github.com/arslaan5/lexiassist/blob/main/assistant/templates/index.html"
    click Templates "https://github.com/arslaan5/lexiassist/blob/main/assistant/templates/login.html"
    click Templates "https://github.com/arslaan5/lexiassist/blob/main/assistant/templates/register.html"
    click Templates "https://github.com/arslaan5/lexiassist/blob/main/assistant/templates/verification_email.html"
    click Templates "https://github.com/arslaan5/lexiassist/blob/main/assistant/templates/404.html"
    click StaticServer "https://github.com/arslaan5/lexiassist/blob/main/assistant/static/script.js"
    click StaticServer "https://github.com/arslaan5/lexiassist/tree/main/assistant/static/images/"
    click Ingestion "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/data_ingestion.py"
    click Embedder "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/data_embedder.py"
    click Retriever "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/data_retriever.py"
    click Transformation "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/data_transformation.py"
    click Uploader "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/data_uploader.py"
    click ResponseHandler "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/response_handler.py"
    click Utils "https://github.com/arslaan5/lexiassist/blob/main/assistant/scripts/utils.py"
    click Docs "https://github.com/arslaan5/lexiassist/tree/main/documents/"
    click Manage "https://github.com/arslaan5/lexiassist/blob/main/manage.py"
    click Requirements "https://github.com/arslaan5/lexiassist/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,stroke-width:1px
    classDef internal fill:#E8F0FF,stroke:#3355AA,stroke-width:1px
    classDef pipeline fill:#F3E8FF,stroke:#AA33AA,stroke-width:1px
    classDef external fill:#FFE8D0,stroke:#CC6600,stroke-width:1px
    classDef db fill:#E8FFE8,stroke:#33AA33,stroke-width:1px
```
