- TypeScript 93%
- Astro 5%
- JavaScript 1.3%
- Dockerfile 0.7%
|
All checks were successful
Build and Publish OCI Image / Build & Push ARM64 OCI Image (push) Successful in 4m40s
Reviewed-on: #31 |
||
|---|---|---|
| .forgejo/workflows | ||
| .yarn | ||
| bin | ||
| docs | ||
| migrations | ||
| src | ||
| .dockerignore | ||
| .env.dist | ||
| .gitignore | ||
| .yarnrc.yml | ||
| AGENTS.md | ||
| astro.config.mjs | ||
| Containerfile | ||
| HOWTO.md | ||
| LICENSE | ||
| modaka-hub.config.json.dist | ||
| MODAKA_HUB_ARCHITECTURE.md | ||
| package.json | ||
| POC_WORKBOOK.md | ||
| README.md | ||
| tsconfig.json | ||
| yarn.lock | ||
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).
🧭 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.mdfiles 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 strictlyreadonlyfor 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 LTSor 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
- MODAKA_HUB_ARCHITECTURE.md — Strategic vision and detailed component design.
- POC_WORKBOOK.md — Step-by-step reproduction and verification workbook.
- HOWTO.md — Curator usage scenarios and common workflows.
- AGENTS.md — LLM coding agent instructions and conventions.
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/extractwrites 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.