Modaka Studio: Curation Workbench, Batch Ingestion Engine & OKF Packaging https://studio.modaka.io
  • TypeScript 93%
  • Astro 5%
  • JavaScript 1.3%
  • Dockerfile 0.7%
Find a file
Olivier Lépine 8df732e7e1
All checks were successful
Build and Publish OCI Image / Build & Push ARM64 OCI Image (push) Successful in 4m40s
Merge pull request 'ci: remove the step writing the image tag into a deployment repository' (#31) from ci/30-remove-deploy-step into develop
Reviewed-on: #31
2026-11-17 11:10:25 +00:00
.forgejo/workflows ci: keep the note on prerelease dependencies (#30) 2026-11-17 11:39:15 +01:00
.yarn ci: remove the step writing the image tag into a deployment repository (#30) 2026-11-17 11:37:03 +01:00
bin Merge pull request 'feat: tenant administration from the Studio, for instance administrators' (#23) from feat/22-tenant-administration into develop 2026-11-16 20:46:15 +00:00
docs feat: side menu and administration pages (#25) 2026-11-17 10:02:59 +01:00
migrations feat: local accounts and OpenID Connect sign-in, without Supabase (#12) 2026-11-16 11:58:35 +01:00
src Merge branch 'develop' into feat/25-app-shell 2026-11-17 09:08:57 +00:00
.dockerignore fix: remove legacy client references and real-world example data 2026-11-08 11:39:16 +01:00
.env.dist feat: instance administrators from a group of the identity provider (#20) 2026-11-16 21:32:57 +01:00
.gitignore fix: remove legacy client references and real-world example data 2026-11-08 11:39:16 +01:00
.yarnrc.yml refactor(neutrality): remove all downstream Brad references (#11) 2026-09-21 16:17:34 +02:00
AGENTS.md Merge branch 'develop' into feat/25-app-shell 2026-11-17 09:08:57 +00:00
astro.config.mjs feat: local accounts and OpenID Connect sign-in, without Supabase (#12) 2026-11-16 11:58:35 +01:00
Containerfile feat: tenant registry and tenant-scoped requests (#7) 2026-11-15 19:21:05 +01:00
HOWTO.md feat!: classification facets come from the configuration (#24) 2026-11-17 09:54:44 +01:00
LICENSE chore: add the AGPL-3.0 licence file and align metadata 2026-11-08 11:44:02 +01:00
modaka-hub.config.json.dist feat!: classification facets come from the configuration (#24) 2026-11-17 09:54:44 +01:00
MODAKA_HUB_ARCHITECTURE.md refactor(neutrality): remove all downstream Brad references (#11) 2026-09-21 16:17:34 +02:00
package.json chore(release): version 0.2.0 (#16) 2026-11-16 21:23:20 +01:00
POC_WORKBOOK.md refactor(neutrality): remove all downstream Brad references (#11) 2026-09-21 16:17:34 +02:00
README.md feat!: classification facets come from the configuration (#24) 2026-11-17 09:54:44 +01:00
tsconfig.json feat(bookworm): complete initial PoC with CoreUX integration, Modaka background queue, and world-agronomy dataset 2026-08-23 19:11:36 +02:00
yarn.lock chore(deps): add @quatrain/auth-local (#12) 2026-11-16 12:30:24 +01:00

Modaka Studio 🌐📚

Collaborative Open Knowledge Curation, Central Authority & Multi-Axial Extraction Platform
Powered by Quatrain Core, Astro 5, React 18, and the Open Knowledge Format (OKF v0.1).

License: AGPL-3.0 Node: >=22.0.0 Astro: 5.x Format: OKF v0.1 OCI Container


🧭 1. Overview & Vision

Modaka Studio is the central scientific and normative authority platform of the Quatrain knowledge ecosystem. It is engineered for expert collectives, scientific institutions, and technical organizations to ingest, curate, qualify, and distribute structured knowledge across orthogonal taxonomy axes.

While decentralized instances (Modaka App / PWA client hubs) serve individual organizations and field practitioners with hyper-personalized local-first data, Modaka Studio acts as the global Source of Authority (SOA):

  • Central Authority Repository (quatrain/authority): Manages normative, verified scientific knowledge with strict revision tracking.
  • Multi-Tenant Collaboration & RBAC: Provides secure multi-curator workflows with fine-grained role-based access control; every change is a Git commit (a dedicated audit trail is on the Roadmap).
  • Contextual Extraction Engine: Filters and exports targeted subsets of the authority knowledge base into dedicated client repositories.
  • Dynamic Authority Scoring: Aggregates anonymous telemetry and usage feedback from downstream nodes to guide gap analysis and continuous curation.

🏗️ 2. Architectural Topology

flowchart TD
    subgraph Ingestion ["1. Multi-Source Ingestion Pipeline"]
        RawPDF["PDF Papers & Manuals"] --> Dropzone["Dropzone UI (@quatrain/ux-dropzone)"]
        RawNotes["Field Reports & Notes"] --> Dropzone
        Dropzone --> WorkerQueue["Async SQLite Task Queue (@quatrain/queue-sqlite)"]
        WorkerQueue --> OCR["Text Extraction (pdf-parse)"]
        OCR --> Gemini["Gemini AI Structuring & Tagging"]
        Gemini --> WikiLink["Wikipedia Concept Auto-Linking"]
    end

    subgraph Hub ["2. Modaka-Hub Authority Core"]
        WikiLink --> CurationWorkbench["Curation Workbench (@quatrain/ux-curation)"]
        CurationWorkbench --> Taxonomy["4-Axes Dynamic Taxonomy (@quatrain/ux-taxonomy)"]
        Taxonomy --> OKF["OKF v0.1 Repository (Git-Native Local Storage)"]
        OKF --> RBAC["Local accounts, OpenID Connect & RBAC (@quatrain/auth-rbac)"]
    end

    subgraph Distribution ["3. Selective Extraction & Downstream Delivery"]
        OKF --> ExtractionEngine["Extraction Engine (/api/extract)"]
        ContextProfile["Target Context Profile (JSON)"] --> ExtractionEngine
        ExtractionEngine -->|Selective Git Fork| Client1["Downstream Node 1 (Modaka Local / PWA)"]
        ExtractionEngine -->|Selective Git Fork| Client2["Downstream Node 2 (Vertical Distribution)"]
    end

    subgraph Feedback ["4. Telemetry & Continuous Improvement"]
        Client1 -.->|Anonymous Telemetry| TelemetryAPI["Telemetry Ingestion (/api/telemetry)"]
        Client2 -.->|Relevance Feedback| TelemetryAPI
        TelemetryAPI --> Analytics["Authority Scoring & Gap Analysis"]
        Analytics --> CurationWorkbench
    end

⚡ 3. Key Capabilities

A. Open Knowledge Format (OKF v0.1) & Lineage Contract

Every document curated or exported strictly conforms to the Open Knowledge Format standard:

  • Strict Lineage Header: Bounded by flat YAML frontmatter declaring soa, revision, type, title, and dynamic taxonomy tags.
  • Semantic Slugs: Lowercase slugified directory paths (content/<category>/<slug>.md), eliminating arbitrary UUIDs.
  • Progressive Disclosure: Token-efficient hierarchical index.md files generated per category for optimal navigation by human users and AI agents.

B. Taxonomy and Classification Facets

Both are declared by the instance in modaka-hub.config.json; the code names none.

  • Axes (axes): the top-level themes documents are filed under, each with its folder.
  • Facets (facets): optional classification dimensions of the instance's own domain, for example a region, an audience or a product line. None by default.
"facets": [
  { "id": "regions", "label": "Regions", "weight": 30 },
  { "id": "audiences", "label": "Audiences", "description": "Who the document is for" }
]

A facet is stored as a flat list under its identifier in the front matter of a document (regions: [north]). The declared facets filter the document list (/api/curate?regions=north) and score extractions: a document gains the weight of a facet (default 20, from 0 to 100) when it lists or mentions a requested value. An identifier is lowercase letters, digits and underscores, and cannot be a field every document has (title, tags, category…).

C. Asynchronous Non-Blocking Worker Queue

Heavy document parsing (PDF OCR, LLM extraction, Wikipedia concept lookup) runs through @quatrain/queue-sqlite. The foreground UI remains responsive with sub-second latency while progress is streamed in real time via @quatrain/ux-dropzone.

D. Dual-Mode Curation Workbench

Curators can seamlessly toggle between:

  • Visual Form Editor: Guided inputs with autocomplete, tag selectors, and validation constraints.
  • Raw YAML Editor: Instant Monaco/Ace-style syntax-highlighted YAML editing with fail-fast validation.

E. Enterprise RBAC & Field-Level Security

  • Accounts kept by the instance: password sign-in and optional OpenID Connect sign-in (authorization code flow with PKCE), with revocable sessions in an HTTP-only cookie.
  • Domain Whitelisting: Strict email domain gating configurable via ALLOWED_EMAIL_DOMAINS.
  • Granular Roles:
    • admin: Full administrative control, remote Git push, taxonomy schema modifications.
    • curator: Ingestion, document qualification, local Git commit.
    • reviewer: Scientific validation and peer review before publication.
    • extractor: Generation of contextual packs and selective client repository forks.
  • Field-Level Security (FLS): Lineage fields (soa, revision) are strictly readonly for non-admin users.

F. Contextual Extraction Engine (/api/extract)

Extracts the documents of the authority repository scored against requested facet values ({ "userId", "facets": { "regions": ["north"] } }) and packages them into an OKF tree.


📁 4. Project Structure

modaka-studio/
├── .forgejo/
│   └── workflows/
│       └── build-oci.yaml          # CI: ARM64 OCI image build & publish to qtrn.io
├── config/                         # System configuration files
├── docs/                           # Architectural diagrams & specifications
├── src/
│   ├── components/                 # React UI components (Workbench, Dropzone, Taxonomy)
│   ├── layouts/                    # Astro base layouts
│   ├── lib/
│   │   ├── ai/                     # AI adapters (provider chosen by AI_PROVIDER)
│   │   ├── auth/                   # Sign-in routes (password, OpenID Connect) & RBAC middleware
│   │   ├── config.ts               # Fail-fast configuration container (@quatrain/config)
│   │   ├── git-sync.ts             # Git synchronization & atomic commits
│   │   └── queue.ts                # SQLite background worker queue
│   ├── middleware.ts               # Edge request interceptor & session handler
│   └── pages/
│       ├── api/                    # RESTful endpoints (curate, extract, queue, git)
│       ├── index.astro             # Main Curation Workbench interface
│       └── login.astro             # Authentication & SSO entrypoint
├── .dockerignore                   # Docker build context exclusions
├── .yarnrc.yml                     # Yarn Berry config (nodeLinker: node-modules)
├── astro.config.mjs                # Astro 5 configuration (Node standalone SSR)
├── Containerfile                   # Production multi-stage OCI Containerfile
├── modaka-hub.config.json.dist     # Default configuration template
└── package.json                    # Workspace manifests and dependencies

🚀 5. Getting Started

Prerequisites

  • Node.js: v22.x LTS or higher
  • Corepack & Yarn: Yarn Berry (v4.x)
  • Git: Installed and available in PATH
  • Podman (or Docker): For local container validation

Installation

# 1. Clone repository
git clone https://git.qtrn.io/modaka/studio.git
cd studio

# 2. Enable Corepack and install dependencies
corepack enable
yarn install

# 3. Initialize configuration files
cp .env.dist .env
cp modaka-hub.config.json.dist modaka-hub.config.json

Environment Variables

Configure the following variables in .env:

# Application Server
PORT=4322
HOST=0.0.0.0
NODE_ENV=development

# Instance database (PostgreSQL): accounts, sessions and tenants
DATABASE_HOST=127.0.0.1
DATABASE_NAME=studio
DATABASE_USER=studio_app
DATABASE_PASSWORD=your-password

# Optional sign-in through an OpenID Connect provider
# OIDC_ISSUER=https://auth.example.org/realms/main
# OIDC_CLIENT_ID=studio
# OIDC_CLIENT_SECRET=
# PUBLIC_BASE_URL=https://studio.example.org
ALLOWED_EMAIL_DOMAINS=*

# AI provider: gemini | deepseek | qwen | openai (any OpenAI-compatible endpoint)
AI_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-api-key
GEMINI_MODEL=gemini-2.5-flash

# Storage & OKF Data
OKF_DATA_DIR=/app/data/okf
OKF_SOA=quatrain/authority

Model Providers

Structuring goes through the @quatrain/ai port; the provider is chosen by AI_PROVIDER, each with <PROVIDER>_API_KEY, <PROVIDER>_MODEL and, except for Gemini, <PROVIDER>_BASE_URL. For a local OpenAI-compatible server (Ollama, llama.cpp, vLLM):

AI_PROVIDER=openai
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=llama3.1
OPENAI_API_KEY=local   # required by the configuration, ignored by local servers

OCR of scanned documents still requires a Gemini model (see Roadmap).

Authentication

Accounts and sessions live in the instance database (PostgreSQL), through @quatrain/auth-local: no external authentication service is needed. Users sign in with a password, and optionally through any OpenID Connect provider (Keycloak, Authentik, Entra ID…) with @quatrain/auth-oidc-client. Accounts are managed with yarn admin account:*. Roles and field permissions are enforced by @quatrain/auth-rbac. See docs/ACCOUNTS.md.

Development Server

yarn dev

Open http://localhost:4322 in your browser.

Running Automated Tests

yarn test

Production Build

# Build standalone Astro SSR bundle
yarn build

# Start production server
node dist/server/entry.mjs

🐳 6. Containerization & Deployment

Modaka-Hub is packaged as a standard OCI container conforming to rootless and unprivileged execution standards.

Local Container Build (Podman / Docker)

# Build the container image
podman build -t modaka/studio:latest -f Containerfile .

# Run the container
podman run -d \
  -p 4322:4322 \
  --name modaka-studio \
  --env-file .env \
  -v ./data:/app/data/okf:Z \
  modaka/studio:latest

Container Construction Chain (Inheritance Model)

Modaka-Hub serves as the base engine container image (qtrn.io/modaka/studio:latest). Downstream vertical distributions (such as domain-specific client engines or local instances) build directly on top of this image without recompiling the application bundle:

# Downstream Containerfile Example
FROM qtrn.io/modaka/studio:latest

# Inject organization-specific taxonomy and domain configuration
COPY modaka-hub.config.json /app/modaka-hub.config.json

ENV PORT=4322
CMD ["node", "./dist/server/entry.mjs"]

📚 7. Technical Documentation


Roadmap

In progress or planned; not available yet:

  • Local models for every capability: OCR through the AI port, local embeddings.
  • Traceability: event log of LLM-judge verdicts, of human confirmations (reviewer, date) and of provenance events (creation, update, validation, summary, transcription, transfer to a downstream instance). Today the history of a document is its Git history, committed with the server identity.
  • Governed sharing: extracted subsets delivered to downstream instances as Git forks (today /api/extract writes a filtered copy locally), with feedback flowing back upstream.
  • Q/A regression tests replayed on every ingestion.
  • Generic OIDC authentication.

📜 8. License

Distributed under the AGPL-3.0-only License. See LICENSE for full terms.
Copyright © 2026 Quatrain Technologies SAS.