# t-act/local-llm-app architecture

> Architecture diagram of the GitHub repository t-act/local-llm-app, 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/t-act/local-llm-app
- Repository: https://github.com/t-act/local-llm-app

## Overview

##### Project type and purpose
- From the file tree, this is a full-stack web application.
- Frontend: A React/TypeScript SPA powered by Vite in the `frontend/` folder.
- Backend: A Python service (`backend/main.py`), likely exposing an HTTP API.
- Local LLM integration: `local_llm.py` at the repo root suggests the backend loads or wraps a local language model.
- No database files appear, so the primary data flows are between UI, API, and the local LLM.

##### File structure
- Top-level: `.gitignore`, Python-version config, `pyproject.toml`/`uv.lock` (Poetry or similar), `plan.txt`.
- `frontend/`:
- `package.json` + lockfile
- `vite.config.ts` → Vite build/dev server
- `src/`: React components (`App.tsx`, `main.tsx`), CSS, config files.
- `backend/`: Single `main.py`, so a lightweight service (e.g., FastAPI, Flask).
- `local_llm.py`: separate module for loading/running a local language model.
- No `database/` folder or SQL scripts, so persistence is either in-memory or omitted.

##### README
- In this case it’s empty, so rely on file names and conventions:
- `backend/main.py` → main entrypoint for the API
- `local_llm.py` → encapsulates LLM logic

##### Main components
a. Frontend SPA
- Vite Dev/Build Server
- React UI (`App.tsx` + assets)
b. Backend API Service
- Python app (`main.py`)
- Local LLM module (`local_llm.py`)
c. (Optional) Client’s browser and network
d. (If any) External dependencies (e.g., external APIs, npm registry, Python package index)

##### Relationships and data flows
- Browser ←→ Frontend app (HTTP/WebSocket)
- Frontend → Backend API (HTTP REST or WebSocket calls)
- Backend API → Local LLM module (in-process function calls)
- Backend → (Optional) Logging or file-based persistence
- Build pipelines:
- npm/yarn → Vite → bundled JS/CSS → served to browser
- Poetry/uv → Python dependencies → runs API server

##### Architectural patterns and design principles
- Separation of Concerns: UI vs. API vs. LLM logic.
- Single-page Application (SPA): client-side routing and state.
- Modular backend: keep LLM code in `local_llm.py` for testability and extension.
- Minimal deployment footprint: no heavyweight database, no microservices (monolith + plugin).

##### Relevant technologies
- Frontend: React, TypeScript, Vite, ESLint
- Backend: Python (likely FastAPI/Flask), Poetry/pyproject, uvicorn (inferred from `uv.lock`)
- Local LLM: any Python library (e.g., transformers, llama-cpp binding) abstracted in `local_llm.py`

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser"]:::external

    subgraph "Frontend Layer"
        NPMPkg["npm/yarn"] 
        ViteDev["Vite Dev/Build Server"]
        ReactUI["React UI Components"]
    end

    subgraph "Backend Layer"
        API["Python API Service"]
        LLM["Local LLM Module"]
    end

    PyConfig["Poetry/Dependencies"]
    Assets["Bundled JS/CSS"]
    Plan["High-level Project Plan/Notes"]

    Browser -->|"UI (HTTP/WebSocket)"| ReactUI
    ReactUI -->|"API Requests (HTTP)"| API
    API -->|"calls"| LLM
    LLM -->|"returns"| API
    API -->|"API Responses (HTTP)"| ReactUI

    NPMPkg --> ViteDev
    ViteDev --> Assets
    Assets --> Browser

    PyConfig --> API

    click NPMPkg "https://github.com/t-act/local-llm-app/blob/main/frontend/package.json"
    click ViteDev "https://github.com/t-act/local-llm-app/blob/main/frontend/vite.config.ts"
    click ReactUI "https://github.com/t-act/local-llm-app/blob/main/frontend/src/App.tsx"
    click API "https://github.com/t-act/local-llm-app/blob/main/backend/main.py"
    click LLM "https://github.com/t-act/local-llm-app/blob/main/local_llm.py"
    click PyConfig "https://github.com/t-act/local-llm-app/blob/main/pyproject.toml"
    click Plan "https://github.com/t-act/local-llm-app/blob/main/plan.txt"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ml fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef note fill:#F0F0F0,stroke:#333,stroke-width:1px

    class NPMPkg,ViteDev,ReactUI frontend
    class API,PyConfig backend
    class LLM ml
    class Plan note
    class Browser external
```
