# pupipatsk/nanollada architecture

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

- Interactive diagram: https://gitdiagram.com/pupipatsk/nanollada
- Repository: https://github.com/pupipatsk/nanollada

## Overview

##### Project Type and Purpose
- This is an NLP research and fine‐tuning project built around LLaDA (Large Language Diffusion with Masking).
- It combines data pipelines, model training & evaluation scripts, serverless inference via Modal, Jupyter notebooks for experimentation, and a Next.js-based frontend for demoing or visualizing results.

##### Main Components
A. Data Layer
– Raw dataset (Huggingface “nakhun/thaisum” CSV files in `/data`).
– Pre‐processing utilities (`src/utils/csv_to_parquet.py`).
– Versioned score & report files under `/data/score` and `/data/report`.
B. Training & Fine-Tuning Pipeline
– Modal jobs for fine-tuning (`modal/fine_tune.py`).
– Model checkpoints and logs (implicitly managed by Modal).
– Poetry–managed environment (`pyproject.toml`, `.venv/`).
C. Inference & Evaluation
– Base‐model inference (`modal/inference-base.py`) and fine‐tuned inference (`modal/inference.py`).
– Evaluation scripts under `/eval` (`2025-05-08-eval-parallel.py`, `summarize_evals.py`).
D. Experimentation Notebooks
– Various Jupyter notebooks in `/notebooks` used for POC, evaluation, refactoring.
E. Web Frontend
– Next.js 13 app in `/web` with React/TypeScript components (`/web/app`, `/web/components`, `/web/hooks`, `/web/lib`).
– Styling via Tailwind (`tailwind.config.ts`), global CSS.
– Entry point (`web/app/page.tsx`), layout, theme provider, and summarizer utility (`web/lib/summarizer.ts`).
F. External Services
– Huggingface Dataset API (for downloading “thaisum”).
– Modal Cloud (serverless compute).
– Optional: GitHub Actions or local scheduler (not explicitly shown but implied for CI).

##### Relationships & Data Flows
- From Modal Fine‐tune → Model artifacts → Modal Inference → Generated summaries.
- From Generated summaries → Evaluation scripts → Score outputs in `/data/score`.
- Web Frontend calls a REST or RPC endpoint (hosted via Modal inference) to fetch summaries; renders via React components.
- Jupyter notebooks connect to the same Poetry virtual env and may trigger local versions of training/inference or pull results from `/data`.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
– Data ingestion/pre‐processing, training, inference, evaluation, and presentation are distinct layers.
- Serverless Compute:
– Modal functions decouple compute and orchestration.
- Modular Code Organization:
– Python modules (`src/utils`) vs. JS/TS modules (`web/components`, `web/lib`).
- Experimentation vs. Production Paths:
– Notebooks for R&D, Modal scripts for reproducible runs, Web app for consumer‐facing demos.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        direction TB
        HF["Huggingface Dataset API"]:::external
        MC["Modal Cloud"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData["Raw Dataset"]:::data
        PreProc["Pre-processing Service\n(Python, Poetry)"]:::compute
        ProcData["Processed Parquet Files"]:::data
        Scores["Score Files"]:::data
        Reports["Report Files"]:::data
    end

    %% Compute Layer
    subgraph "Compute Layer"
        direction TB
        FineTune["Modal Fine-tune Worker\n(modal/fine_tune.py)"]:::compute
        InferenceBase["Base-Model Inference Worker\n(modal/inference-base.py)"]:::compute
        InferenceFT["Fine-Tuned Inference Worker\n(modal/inference.py)"]:::compute
        Upload["Modal Upload Script\n(modal/upload.py)"]:::compute
        EvalParallel["Eval Parallel Script\n(eval/2025-05-08-eval-parallel.py)"]:::compute
        EvalSumm["Eval Summarizer\n(eval/summarize_evals.py)"]:::compute
    end

    %% Notebooks
    subgraph "Experimentation Notebooks"
        direction TB
        NBDir["Notebooks Directory\n(.ipynb files)"]:::compute
        NBArchive["Experiment Archive\n(notebooks/Experiment archive/)"]:::compute
    end

    %% Frontend
    subgraph "Web Frontend"
        direction TB
        NextApp["Next.js App Root"]:::ui
        Page["Entry Page\n(page.tsx)"]:::ui
        Layout["Layout Component\n(layout.tsx)"]:::ui
        Globals["Global Styles\n(globals.css)"]:::ui
        Components["UI Components\n(web/components/)"]:::ui
        UIkit["UI Kit\n(web/components/ui/)"]:::ui
        HooksMobile["use-mobile Hook"]:::ui
        HooksToast["use-toast Hook"]:::ui
        LibSumm["Summarizer Util\n(web/lib/summarizer.ts)"]:::ui
        LibUtils["Utils\n(web/lib/utils.ts)"]:::ui
        ConfigTail["Tailwind Config\n(tailwind.config.ts)"]:::ui
        ConfigNext["Next.js Config\n(next.config.mjs)"]:::ui
        ConfigTS["TypeScript Config\n(tsconfig.json)"]:::ui
        PKG["package.json"]:::ui
        Lock["pnpm-lock.yaml"]:::ui
    end

    %% Data Flows
    HF -->|download CSV| RawData
    RawData -->|CSV→Parquet| PreProc
    PreProc --> ProcData
    ProcData -->|training data| FineTune
    FineTune -->|model artifacts| Upload
    Upload --> MC
    MC -->|trigger| InferenceBase
    MC -->|trigger| InferenceFT
    InferenceBase -->|base summaries| Scores
    InferenceFT -->|fine-tuned summaries| Scores
    Scores --> EvalParallel
    Scores --> EvalSumm
    EvalParallel --> Reports
    EvalSumm --> Reports

    %% Frontend & Notebooks interactions
    InferenceBase -->|POST /infer| NextApp
    InferenceFT -->|POST /infer-ft| NextApp
    ProcData -->|access| NBDir
    InferenceBase -->|local call| NBDir
    InferenceFT -->|local call| NBDir

    %% Notebook archive
    NBDir --> NBArchive

    %% Frontend structure
    NextApp --> Page
    NextApp --> Layout
    NextApp --> Globals
    NextApp --> Components
    Components --> UIkit
    NextApp --> HooksMobile
    NextApp --> HooksToast
    NextApp --> LibSumm
    NextApp --> LibUtils
    NextApp --> ConfigTail
    NextApp --> ConfigNext
    NextApp --> ConfigTS
    NextApp --> PKG
    NextApp --> Lock

    %% Click Events
    click RawData "https://github.com/pupipatsk/nanollada/tree/main/data/"
    click Reports "https://github.com/pupipatsk/nanollada/blob/main/data/report/score_summary_report.txt"
    click Scores "https://github.com/pupipatsk/nanollada/tree/main/data/score/"
    click PreProc "https://github.com/pupipatsk/nanollada/blob/main/src/utils/csv_to_parquet.py"
    click FineTune "https://github.com/pupipatsk/nanollada/blob/main/modal/fine_tune.py"
    click Upload "https://github.com/pupipatsk/nanollada/blob/main/modal/upload.py"
    click InferenceBase "https://github.com/pupipatsk/nanollada/blob/main/modal/inference-base.py"
    click InferenceFT "https://github.com/pupipatsk/nanollada/blob/main/modal/inference.py"
    click EvalParallel "https://github.com/pupipatsk/nanollada/blob/main/eval/2025-05-08-eval-parallel.py"
    click EvalSumm "https://github.com/pupipatsk/nanollada/blob/main/eval/summarize_evals.py"
    click NBDir "https://github.com/pupipatsk/nanollada/tree/main/notebooks/"
    click NBArchive "https://github.com/pupipatsk/nanollada/tree/main/notebooks/Experiment archive/"
    click NextApp "https://github.com/pupipatsk/nanollada/tree/main/web/app/"
    click Page "https://github.com/pupipatsk/nanollada/blob/main/web/app/page.tsx"
    click Layout "https://github.com/pupipatsk/nanollada/blob/main/web/app/layout.tsx"
    click Globals "https://github.com/pupipatsk/nanollada/blob/main/web/app/globals.css"
    click Components "https://github.com/pupipatsk/nanollada/tree/main/web/components/"
    click UIkit "https://github.com/pupipatsk/nanollada/tree/main/web/components/ui/"
    click HooksMobile "https://github.com/pupipatsk/nanollada/blob/main/web/hooks/use-mobile.tsx"
    click HooksToast "https://github.com/pupipatsk/nanollada/blob/main/web/hooks/use-toast.ts"
    click LibSumm "https://github.com/pupipatsk/nanollada/blob/main/web/lib/summarizer.ts"
    click LibUtils "https://github.com/pupipatsk/nanollada/blob/main/web/lib/utils.ts"
    click ConfigTail "https://github.com/pupipatsk/nanollada/blob/main/web/tailwind.config.ts"
    click ConfigNext "https://github.com/pupipatsk/nanollada/blob/main/web/next.config.mjs"
    click ConfigTS "https://github.com/pupipatsk/nanollada/blob/main/web/tsconfig.json"
    click PKG "https://github.com/pupipatsk/nanollada/blob/main/web/package.json"
    click Lock "https://github.com/pupipatsk/nanollada/blob/main/web/pnpm-lock.yaml"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#005ABA
    classDef compute fill:#DFFFE0,stroke:#228B22
    classDef ui fill:#FFE0B2,stroke:#FF8C00
    classDef external fill:#F0F0F0,stroke:#888888
    class RawData,ProcData,Scores,Reports data
    class PreProc,FineTune,InferenceBase,InferenceFT,Upload,EvalParallel,EvalSumm,NBDir,NBArchive compute
    class NextApp,Page,Layout,Globals,Components,UIkit,HooksMobile,HooksToast,LibSumm,LibUtils,ConfigTail,ConfigNext,ConfigTS,PKG,Lock ui
    class HF,MC external
```
