Architecture Overview

​

Monorepo Structure

• Shared code across web, desktop, and backend
• Consistent versioning and dependency management
• Atomic changes across multiple packages
• Easier refactoring and code reuse

​

Monorepo Tooling

• Turborepo - Build orchestration and caching (configured in turbo.jsonc)
• pnpm workspaces - Package management and workspace linking (configured in pnpm-workspace.yaml)
• Cargo workspaces - Rust package management (configured in root Cargo.toml)

packages:
  - 'apps/*'
  - 'packages/*'

​

Directory Structure

modrinth/
├── apps/              # Applications
│   ├── frontend/      # Nuxt 3 website
│   ├── app/           # Tauri desktop shell
│   ├── app-frontend/  # Vue 3 app UI
│   ├── app-playground # App testing environment
│   ├── labrinth/      # Rust backend API
│   ├── daedalus_client # Daedalus CLI client
│   └── docs/          # Documentation (Astro)
├── packages/          # Shared libraries
│   ├── ui/            # Vue component library
│   ├── api-client/    # API client (Labrinth/Archon/Kyros)
│   ├── app-lib/       # Theseus (app backend library)
│   ├── assets/        # Styles, icons, design tokens
│   ├── utils/         # Shared utilities
│   ├── daedalus/      # Minecraft meta API library
│   ├── ariadne/       # Analytics library
│   └── ... (more packages)
├── .github/           # GitHub Actions workflows
├── scripts/           # Build and utility scripts
├── Cargo.toml         # Rust workspace config
├── package.json       # Root package.json
├── pnpm-workspace.yaml # pnpm workspace config
├── turbo.jsonc        # Turborepo config
└── docker-compose.yml # Local development services

​

Applications (apps/)

​

Frontend (Nuxt 3 Website)

• Framework: Nuxt 3 with SSR (Server-Side Rendering)
• Routing: File-based routing in src/pages/
• State: Pinia stores + TanStack Query for server state
• API: @modrinth/api-client via NuxtModrinthClient
• Deployment: Cloudflare Pages

• Project browsing and search
• User authentication and profiles
• Mod/modpack management
• Admin and moderation tools

​

App Frontend (Vue 3)

• Framework: Vue 3 (not Nuxt - no SSR)
• Platform: Runs inside Tauri WebView
• API: @modrinth/api-client via TauriModrinthClient
• IPC: Communicates with Theseus (Rust backend) via Tauri commands

​

App (Tauri Desktop)

• WebView: Hosts app-frontend UI
• Backend: Links theseus (app-lib) for core functionality
• Platforms: Windows, macOS, Linux
• Features: Auto-updates, deep links, system tray, window state

​

Labrinth (Backend API)

• Framework: Actix-Web
• Database: PostgreSQL (primary), ClickHouse (analytics), Redis (cache)
• Search: Meilisearch
• Storage: S3-compatible (files, images)
• Auth: Session-based + API tokens
• API Docs: OpenAPI (utoipa) with Swagger UI

​

Docs (Astro)

​

Other Apps

• app-playground: Testing environment for the desktop app
• daedalus_client: CLI tool for Daedalus protocol

​

Packages (packages/)

​

Frontend Packages (TypeScript)

​

@modrinth/ui

• Vue 3 components (buttons, modals, cards, etc.)
• Cross-platform pages (used in both frontend and app-frontend)
• Composables and utilities
• Storybook for component development
• i18n translations (34 languages)

import { Button, Modal, ProjectCard } from '@modrinth/ui'

​

@modrinth/api-client

• Labrinth API (projects, versions, users)
• Archon API (Modrinth Hosting servers)
• Kyros API (server file management)
• Platform variants: GenericModrinthClient, NuxtModrinthClient, TauriModrinthClient
• Features: auth, retry, circuit breaker
• WebSocket support for real-time server events

import { NuxtModrinthClient, AuthFeature } from '@modrinth/api-client'

​

@modrinth/assets

• Tailwind CSS variables and theme configuration
• SVG icons (auto-generated from icons/ directory)
• Color palettes and semantic tokens

​

@modrinth/utils

​

@modrinth/blog

​

@modrinth/moderation

​

@modrinth/tooling-config

​

Rust Packages

​

theseus (app-lib)

• Profile and instance management
• Mod installation and updates
• Minecraft version management
• Java runtime detection
• Game launching
• Analytics and crash reporting
• Local database (SQLite)

• Tauri commands (IPC)
• Event emitters for progress tracking

​

daedalus

• Minecraft version manifests
• Forge, Fabric, Quilt version data
• Modpack parsing and validation

​

ariadne

​

Other Rust Packages

• modrinth-log: Logging utilities
• modrinth-util: General utilities
• modrinth-maxmind: MaxMind GeoIP integration
• muralpay: Payment processing
• path-util: Cross-platform path utilities
• sqlx-tracing: SQLx query tracing
• labrinth-derive: Derive macros for Labrinth

​

Technology Stack

​

Frontend Stack

​

Backend Stack

​

Desktop App Stack

​

Service Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Clients                             │
├──────────────┬──────────────────┬──────────────────────────┤
│  Web Browser │   Desktop App    │      Mobile (future)     │
│   (Nuxt 3)   │  (Tauri + Vue)   │                          │
└──────┬───────┴────────┬─────────┴──────────────────────────┘
       │                │
       │                └─────────┐
       │                          │
       ▼                          ▼
┌──────────────┐          ┌──────────────┐
│   Labrinth   │          │   Theseus    │
│   (Rust API) │          │ (Local Rust) │
└──────┬───────┘          └──────┬───────┘
       │                          │
       ├──────────┬───────────────┤
       │          │               │
       ▼          ▼               ▼
┌──────────┐ ┌─────────┐   ┌──────────┐
│ PostgreSQL│ │ Meili-  │   │  SQLite  │
│ ClickHouse│ │ search  │   │  (Local) │
│   Redis   │ │         │   │          │
└───────────┘ └─────────┘   └──────────┘
       │
       ▼
┌──────────────┐
│  S3 Storage  │
└──────────────┘

​

API Services

1. Labrinth (api.modrinth.com) - Main REST API
   • Projects, versions, users, teams
   • Search, analytics, moderation
   • Authentication and authorization
2. Archon (archon.modrinth.com) - Modrinth Hosting API
   • Server management
   • Backups and restores
   • WebSocket real-time events
3. Kyros (node-specific) - File management API
   • Server file uploads/downloads
   • Directory browsing
   • File operations

​

Build System

​

Turborepo Configuration

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".nuxt/**", "build/**"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["^build"]
    }
  }
}

• Builds dependencies in the correct order
• Caches build outputs
• Runs tasks in parallel when possible

​

Workspace Dependencies

{
  "dependencies": {
    "@modrinth/ui": "workspace:*",
    "@modrinth/api-client": "workspace:*",
    "@modrinth/assets": "workspace:*"
  }
}

​

Development Workflow

​

Hot Reloading

• Frontend: Vite HMR (Hot Module Replacement)
• Backend: Manual restart (or use cargo-watch)
• Desktop App: Frontend HMR + manual Rust rebuild

​

Deployment

​

Frontend Deployment

• Platform: Cloudflare Pages
• Trigger: Push to main branch
• Build: pnpm pages:build (Nuxt with Cloudflare preset)
• Preview: Automatic PR previews

​

Backend Deployment

• Platform: Docker containers
• Registry: GitHub Container Registry (ghcr.io)
• Orchestration: Kubernetes
• CI: GitHub Actions builds Docker images

​

Desktop App Deployment

• Platform: GitHub Releases
• Build: Cross-platform CI (Windows, macOS, Linux)
• Updates: Tauri auto-updater
• Distribution: Direct download from modrinth.com/app

​

Code Organization Principles

​

Separation of Concerns

• Frontend apps (apps/frontend, apps/app-frontend) contain app-specific logic
• Shared components (packages/ui) contain reusable UI elements
• API client (packages/api-client) handles all backend communication
• Backend (apps/labrinth) handles business logic and data

​

Cross-Platform Pages

​

Dependency Injection

​

Next Steps