ADT Studio

Desktop-first application for automated book production — extract content from PDFs, process through LLM pipelines, and generate formatted output bundles.

Tech Stack

Layer	Technology
Monorepo	pnpm workspaces
Language	TypeScript (strict mode)
Backend	Hono, node-sqlite3-wasm, Zod
Frontend	React + Vite, TanStack (Router, Query, Table, Form), Tailwind CSS
Desktop	Tauri v2
Testing	Vitest

Desktop app — additional requirements

Rust is required for the Tauri desktop wrapper.

Platform-specific dependencies

macOS

• Xcode Command Line Tools:

  xcode-select --install

Windows

• Microsoft C++ Build Tools — install the "Desktop development with C++" workload
• WebView2 — pre-installed on Windows 10 (version 1803+) and Windows 11

Linux

• System dependencies (Debian/Ubuntu):

  sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

Getting Started

Docker (recommended)

Just Docker — no Node.js, no cloning.

Option 1 — download docker-compose.yml from the latest release:

docker compose up          # starts on http://localhost:8080
docker compose up -d       # background
docker compose down        # stop

Set PORT=9000 in a .env file next to docker-compose.yml to change the port.

Option 2 — single command:

docker run -p 8080:80 -v ./books:/app/books ghcr.io/unicef/adt-studio:latest

Open http://localhost:8080. Book data persists in the local ./books/ directory.

Build from source

Requires cloning the repo and Docker.

git clone git@github.com:unicef/adt-studio.git
cd adt-studio

# Build and start (first build takes ~5 min)
docker compose up --build

To change the port, copy .env.example to .env and set PORT=<your port>.

docker compose up --build -d   # background
docker compose logs -f          # logs
docker compose down             # stop

Local development

Prerequisites: Node.js >= 20, pnpm >= 9.

# Clone the repository
git clone git@github.com:unicef/adt-studio.git
cd adt-studio

# Install dependencies (first time only)
pnpm install

# Start dev servers — builds automatically, opens browser
pnpm dev

The browser opens automatically at http://localhost:5173. The API runs at http://localhost:3001. On first run, pnpm dev compiles all packages (~1 min). Subsequent runs are fast (incremental build).

Running the desktop app

With the dev servers running (pnpm dev), open a separate terminal:

pnpm dev:desktop

This launches the Tauri desktop window pointing at the Vite dev server. First run will compile the Rust backend which takes a few minutes — subsequent runs are fast.

Project Structure

adt-studio/
├── packages/                # Shared libraries (@adt/* workspace packages)
│   ├── types/               # Zod schemas — ALL types defined here
│   ├── pipeline/            # Extraction & generation — pure functions
│   ├── llm/                 # LLM client, prompts, caching, cost tracking
│   ├── pdf/                 # PDF extraction
│   └── output/              # Bundle packaging
│
├── apps/                    # Application tier
│   ├── api/                 # Hono HTTP server
│   ├── studio/              # React SPA (Vite + TanStack)
│   └── desktop/             # Tauri v2 desktop wrapper
│
├── templates/               # Layout templates
├── config/                  # Global configuration
└── docs/                    # Documentation
    ├── GUIDELINES.md        # Coding standards & patterns
    ├── DECISIONS.md         # Architecture decision records
    └── architecture.html    # Interactive architecture diagram

Architecture

┌──────────────────────────────────────────┐
│  apps/studio (React)  │  apps/desktop    │
└────────────────┬─────────────────────────┘
                 │ HTTP only
                 ▼
┌──────────────────────────────────────────┐
│            apps/api (Hono)               │
└────────────────┬─────────────────────────┘
                 │ Direct imports
                 ▼
┌──────────────────────────────────────────┐
│  packages/pipeline │ llm │ output        │
└────────────────┬─────────────────────────┘
                 ▼
┌──────────────────────────────────────────┐
│       packages/types │ pdf               │
└──────────────────────────────────────────┘

Frontend apps communicate with the API over HTTP only — they never import from packages directly.

Commands

pnpm install          # Install all dependencies
pnpm dev              # Start dev servers (API + Studio)
pnpm dev:desktop      # Launch Tauri desktop app (requires pnpm dev running)
pnpm build            # Build all packages and apps
pnpm test             # Run tests
pnpm test:coverage    # Run tests with coverage
pnpm typecheck        # TypeScript strict mode check
pnpm lint             # Lint all packages

Core Principles

1. Book-Level Storage — All book data isolated to a single, zippable directory
2. Entity-Level Versioning — Never overwrite; always create new versions with rollback
3. LLM-Level Caching — Hash inputs for cache keys; reruns are instant if unchanged
4. Maximum Transparency — All LLM calls, prompts, and responses are user-inspectable
5. Minimize Dependencies — Flat files over databases when sufficient
6. Pure JS/TS Over Native — WASM over C/C++ bindings for cross-platform portability

Documentation

Document	Description
docs/ARCHITECTURE.md	System architecture, package graph, pipeline model, data flow
docs/DEVELOPER-GUIDE.md	Hosting guide and developer extension reference for third-party teams
CLAUDE.md	Claude Code project configuration
AGENTS.md	Specialized agent definitions
docs/GUIDELINES.md	Full coding standards, security, patterns
docs/DECISIONS.md	Architecture decision records with reasoning
docs/architecture.html	Interactive architecture diagram (open in browser)

License

This project is licensed under GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for details. Original author and copyright holder: UNICEF. See COPYRIGHT.