# harvard-lil/olaw architecture

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

- Interactive diagram: https://gitdiagram.com/harvard-lil/olaw
- Repository: https://github.com/harvard-lil/olaw

## Overview

##### Project type and purpose
- OLAW is a full-stack web application (Flask + Python backend; JS/CSS frontend) that implements a tool-based Retrieval-Augmented Generation (RAG) pipeline for legal research.
- It provides both a browser-based chat UI and a REST API to orchestrate three stages: (a) extract a search statement, (b) perform a search against a legal API, (c) send context+history to an LLM and stream back the completion.

##### File structure
- Top–level:
- wsgi.py – Flask WSGI entry point
- pyproject.toml / setup.cfg – build & dependency config
- .env.example – environment variable template
- olaw/ (Python package)
- views/ui.py – serves index.html and static assets
- views/api/*.py – REST endpoints (`/api/models`, `/api/extract-search-statement`, `/api/search`, `/api/complete`)
- search_targets/ – plugin modules for each legal search target (e.g., courtlistener.py)
- utils/ – env checks, rate-limiter factory, model list discovery
- static/ – JS components (ChatBubble, ChatFlow, ChatInput, dialogs), CSS, state management
- templates/index.html – single‐page shell

##### README for architectural insights
- Pipeline stages and endpoints are documented in “Interacting with the API”
- Describes interchangeable LLM backends (OpenAI vs. Ollama) and pluggable search targets
- Highlights modularity and ease of adding new tools via search_targets

##### Main components & interactions
a. Frontend (Browser)
- index.html + JS/CSS components present chat UI, handle user input & confirmations, display streaming text
b. Backend (Flask App)
- UI controller: serves static assets and template
- API controllers:
- extract-search-statement → calls LLM with prompt to generate `{search_target, search_statement}`
- search → loads appropriate SearchTarget class → performs HTTP call to legal API (e.g., CourtListener)
- complete → collates message, history, and search results → calls LLM endpoint (OpenAI/Ollama) → streams response
- Utils: environment/config loader, rate limiter, available models enumerator
c. External Services
- CourtListener API (or any other legal search target)
- LLM backends: OpenAI’s completions API or local Ollama server

##### Architectural patterns & design principles
- MVC‐style separation: `views/ui.py` (V), static components (C), `views/api` (C) & business logic in `olaw/utils` & `olaw/search_targets` (M)
- Plugin pattern: each `search_targets/*.py` implements a uniform interface for adding new legal APIs
- Pipeline orchestration: sequential stages (extract → search → complete) with confirmation step in the UI
- Environment-driven configuration: `.env` controls LLM endpoints, model choices, prompts

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser (Client)"
        FB["index.html (SPA Shell)"]:::frontend
        CBub["ChatBubble"]:::frontend
        CFlow["ChatFlow"]:::frontend
        CIn["ChatInput"]:::frontend
        IDia["InspectDialog"]:::frontend
        SDia["SettingsDialog"]:::frontend
        State["Client State"]:::frontend
        Styles["Global Stylesheet"]:::frontend
    end

    subgraph "Flask Application"
        WSGI["WSGI Entry Point"]:::backend
        UI["UI Controller"]:::backend
        APImods["Models Endpoint"]:::backend
        APIext["Extract Search Statement"]:::backend
        APIsearch["Search Endpoint"]:::backend
        APIcomplete["Complete Endpoint"]:::backend
        UtilsEnv["Environment Checks"]:::backend
        UtilsLim["Rate Limiter Factory"]:::backend
        UtilsList["Available Models Discovery"]:::backend
        Plugin["CourtListener Plugin"]:::backend
        Config[".env Template"]:::backend
        Build["Build & Dependency Config"]:::backend
    end

    subgraph "External Services"
        LLM["LLM Service (OpenAI/Ollama)"]:::external
        CourtAPI["CourtListener API"]:::external
    end

    %% Browser to Flask UI
    FB -->|"GET /"| UI

    %% WSGI routing
    WSGI --> UI
    WSGI --> APImods
    WSGI --> APIext
    WSGI --> APIsearch
    WSGI --> APIcomplete

    %% API ext search statement flow
    CIn -->|"POST /api/extract-search-statement"| APIext
    APIext -->|"calls LLM"| LLM
    LLM -->|"returns {search_target,statement}"| APIext
    APIext -->|"JSON suggestion"| CBub

    %% API search flow
    CFlow -->|"POST /api/search"| APIsearch
    APIsearch --> Plugin
    Plugin --> CourtAPI
    CourtAPI --> APIsearch
    APIsearch -->|"JSON results"| CFlow

    %% API complete flow
    CFlow -->|"POST /api/complete"| APIcomplete
    APIcomplete -->|"calls LLM"| LLM
    LLM -->|"stream response"| APIcomplete
    APIcomplete -->|"stream chunk"| CFlow

    %% Utils usage
    WSGI --> UtilsEnv
    WSGI --> UtilsLim
    WSGI --> UtilsList
    UI --> UtilsEnv
    APImods --> UtilsList
    APIext --> UtilsEnv
    APIsearch --> UtilsLim

    %% Configuration & build
    Config -.-> UtilsEnv
    Config -.-> APIcomplete
    Build -.-> WSGI

    %% Click Events
    click FB "https://github.com/harvard-lil/olaw/blob/main/olaw/templates/index.html"
    click CBub "https://github.com/harvard-lil/olaw/blob/main/olaw/static/components/ChatBubble.js"
    click CFlow "https://github.com/harvard-lil/olaw/blob/main/olaw/static/components/ChatFlow.js"
    click CIn "https://github.com/harvard-lil/olaw/blob/main/olaw/static/components/ChatInput.js"
    click IDia "https://github.com/harvard-lil/olaw/blob/main/olaw/static/components/InspectDialog.js"
    click SDia "https://github.com/harvard-lil/olaw/blob/main/olaw/static/components/SettingsDialog.js"
    click State "https://github.com/harvard-lil/olaw/blob/main/olaw/static/state.js"
    click Styles "https://github.com/harvard-lil/olaw/blob/main/olaw/static/index.css"

    click WSGI "https://github.com/harvard-lil/olaw/blob/main/wsgi.py"
    click UI "https://github.com/harvard-lil/olaw/blob/main/olaw/views/ui.py"
    click APImods "https://github.com/harvard-lil/olaw/blob/main/olaw/views/api/models.py"
    click APIext "https://github.com/harvard-lil/olaw/blob/main/olaw/views/api/extract_search_statement.py"
    click APIsearch "https://github.com/harvard-lil/olaw/blob/main/olaw/views/api/search.py"
    click APIcomplete "https://github.com/harvard-lil/olaw/blob/main/olaw/views/api/complete.py"

    click Plugin "https://github.com/harvard-lil/olaw/blob/main/olaw/search_targets/courtlistener.py"

    click UtilsEnv "https://github.com/harvard-lil/olaw/blob/main/olaw/utils/check_env.py"
    click UtilsLim "https://github.com/harvard-lil/olaw/blob/main/olaw/utils/get_limiter.py"
    click UtilsList "https://github.com/harvard-lil/olaw/blob/main/olaw/utils/list_available_models.py"

    click Config "https://github.com/harvard-lil/olaw/blob/main/.env.example"
    click Build "https://github.com/harvard-lil/olaw/blob/main/pyproject.toml"

    classDef frontend fill:#cef,stroke:#039;
    classDef backend fill:#cfc,stroke:#090;
    classDef external fill:#fcc,stroke:#900;
```
