# l10nmonster/llm-lab architecture

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

- Interactive diagram: https://gitdiagram.com/l10nmonster/llm-lab
- Repository: https://github.com/l10nmonster/llm-lab

## Overview

##### Project Type and Purpose
- This is a full-stack, single-page Express.js web application (“LLM Lab”) whose purpose is to let users configure and execute translation experiments on Google Sheets data via LLM providers. The frontend is plain HTML/CSS/JS, the backend is Node.js/Express, and the “database” is Google Sheets via the Google Sheets API.

##### File Structure Analysis
- Top-level files:
- server.js — entry point for the Express server
- package.json, jsconfig.json — project metadata and module resolution
- .gitignore, LICENSE, README.md
- public/ — static UI assets (index.html, style.css, script.js)
- routes/apiRoutes.js — Express route handlers for the API endpoints (/api/providers, /api/project)
- services/ — core business logic split into:
- googleAuth.js — handles OAuth2 authentication flow with Google
- googleSheets.js — reads/writes data to Sheets, handles formatting
- l10nMonster.js — orchestrates translation calls to LLM providers
- utils/spreadsheetUtils.js — helper functions (parsing IDs, range calculations)

##### Key Architectural Insights from README
- Single-page UI served by Express
- Two REST endpoints:
GET /api/providers → returns list of LLM providers
POST /api/project → handles test configuration, orchestrates data flow
- Google OAuth2 for secure authentication (credentials.json, token.json)
- Modular codebase following a simple “routes → services → utils” layering
- External dependencies: Google Sheets API, multiple LLM provider APIs (mocked or real)

1) Browser Client (UI)
2) Express Server
- Static File Server (public/)
- API Layer (routes/apiRoutes.js)
- Service Layer (services/googleAuth, googleSheets, l10nMonster)
- Utility Layer (utils/spreadsheetUtils)
3) External Service: Google OAuth2 / Google Sheets API
4) External Service: LLM Provider APIs (e.g., Lara, MMT, Gemini, GCT)
1) Browser → Express (HTTP GET /) → serves index.html, CSS, JS
2) Browser → Express (AJAX GET /api/providers) → returns provider list
3) Browser → Express (AJAX POST /api/project with config payload)
→ Express calls googleAuth to ensure valid token
→ googleSheets.readData(spreadsheetID, range)
→ l10nMonster.translateBatch(data, instructions) calls LLM APIs in parallel
→ l10nMonster returns translated results to service layer
→ googleSheets.writeData(newSheetID, formattedResults)
→ Express returns success + results‐sheet URL to Browser
c. Architectural Patterns and Principles:
- Layered architecture:
Presentation (public/) → API (routes) → Business Logic (services) → Utilities
- Separation of concerns: authentication, data I/O, translation logic each in its own module
- Asynchronous orchestration: promise‐based calls to Google and LLM APIs
- No persistent in‐app database; Google Sheets acts as both input and output store
d. Technologies & Frameworks:
- Node.js, Express.js
- googleapis Node.js client (OAuth2 + Sheets API)
- Vanilla HTML/CSS/JS on the client
- External LLM provider endpoints (REST/HTTP)

##### Essential Elements to Capture
- OAuth2 flow: client ↔ googleAuth ↔ Google OAuth2 endpoint
- Sheets read/write loop: config → googleSheets → Google Sheets API
- Translation loop: data → l10nMonster → LLM provider APIs → results
- Final result return path back to the Browser UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Zone
    subgraph "Frontend" 
        direction TB
        Browser["Browser Client"]:::frontend
    end

    %% Backend Zone
    subgraph "Backend"
        direction TB
        Server["Express Server (server.js)"]:::backend
        subgraph "Static File Server"
            direction TB
            Index["index.html"]:::backend
            Style["style.css"]:::backend
            Script["script.js"]:::backend
        end
        subgraph "API Layer"
            direction TB
            APILayer["API Layer (routes/apiRoutes.js)"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            Auth["Auth Service<br/>services/googleAuth.js"]:::backend
            Sheets["Sheets Service<br/>services/googleSheets.js"]:::backend
            Translate["Translation Service<br/>services/l10nMonster.js"]:::backend
        end
        Utils["Utils Layer (utils/spreadsheetUtils.js)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleOAuth["Google OAuth2 Endpoint"]:::external
        GoogleSheetsAPI["Google Sheets API"]:::external
        LLMProviders["LLM Provider APIs"]:::external
    end

    %% Data Flows
    Browser -->|"GET /"| Server
    Server -->|"serves static assets"| Index
    Server --> Style
    Server --> Script
    Index --> Browser
    Style --> Browser
    Script --> Browser

    Browser -->|"GET /api/providers"| APILayer
    APILayer -->|"returns provider list"| Browser

    Browser -->|"POST /api/project (config JSON)"| APILayer

    APILayer -->|"ensure token"| Auth
    Auth -->|"request auth code"| GoogleOAuth
    GoogleOAuth -->|"auth token"| Auth
    Auth -->|"token"| APILayer

    APILayer -->|"read sheet data"| Sheets
    Sheets -->|"read request"| GoogleSheetsAPI
    GoogleSheetsAPI -->|"sheet data"| Sheets
    Sheets -->|"data"| Translate

    Translate -->|"translateBatch(data, instructions)"| LLMProviders
    LLMProviders -->|"translated results"| Translate
    Translate -->|"results"| Sheets

    Sheets -->|"write request"| GoogleSheetsAPI
    GoogleSheetsAPI -->|"write confirmation"| Sheets
    Sheets -->|"results-sheet URL"| APILayer

    APILayer -->|"success + results-sheet URL"| Browser

    %% Utils Dependencies
    Auth --> Utils
    Sheets --> Utils
    Translate --> Utils

    %% Click Events
    click Index "https://github.com/l10nmonster/llm-lab/blob/main/public/index.html"
    click Style "https://github.com/l10nmonster/llm-lab/blob/main/public/style.css"
    click Script "https://github.com/l10nmonster/llm-lab/blob/main/public/script.js"
    click Server "https://github.com/l10nmonster/llm-lab/blob/main/server.js"
    click APILayer "https://github.com/l10nmonster/llm-lab/blob/main/routes/apiRoutes.js"
    click Auth "https://github.com/l10nmonster/llm-lab/blob/main/services/googleAuth.js"
    click Sheets "https://github.com/l10nmonster/llm-lab/blob/main/services/googleSheets.js"
    click Translate "https://github.com/l10nmonster/llm-lab/blob/main/services/l10nMonster.js"
    click Utils "https://github.com/l10nmonster/llm-lab/blob/main/utils/spreadsheetUtils.js"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef backend fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef external fill:#fdd835,stroke:#333,stroke-width:1px;
```
