From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001
From: Natsuu <natsukawa247@outlook.com>
Date: Fri, 27 Feb 2026 17:18:25 +0800
Subject: Restructure docs into manual/development and add implementation docs
 (#94)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary by Sourcery

Restructure documentation into separate manual and development sections,
introduce detailed internal implementation docs for auth/Java/mod
loaders, and update site navigation, landing page links, and MDX tooling
(Mermaid, card styling) to match the new structure and tech stack.

Enhancements:
- Enable Mermaid rendering support in the docs app and add a reusable
Mermaid React component.
- Refine Docs page rendering by customizing Card styling and removing
redundant in-page titles/descriptions rendered by the layout.
- Align docs source configuration and routing comments with the new
manual-based default paths.

Documentation:
- Split user-facing docs under a new manual section and move contributor
content into a dedicated development section for both English and
Chinese.
- Add comprehensive internal implementation documentation covering
authentication, Java management, mod loader/version merging, event bus,
and architecture patterns in both English and Chinese.
- Update existing feature docs (mod loaders, Java, authentication) and
getting-started/troubleshooting pages to be more conceptual, pointing to
implementation docs for technical details.
- Refresh architecture docs to reflect the React/Zustand frontend stack
and add Mermaid-based architecture diagrams.
- Adjust navigation labels, home-page CTAs, and doc links to target the
new manual/development structure and routes.

---------

Co-authored-by: 简律纯 <i@jyunko.cn>
---
 packages/docs/content/en/architecture.mdx | 281 ------------------------------
 1 file changed, 281 deletions(-)
 delete mode 100644 packages/docs/content/en/architecture.mdx

(limited to 'packages/docs/content/en/architecture.mdx')

diff --git a/packages/docs/content/en/architecture.mdx b/packages/docs/content/en/architecture.mdx
deleted file mode 100644
index 5f55c5e..0000000
--- a/packages/docs/content/en/architecture.mdx
+++ /dev/null
@@ -1,281 +0,0 @@
----
-title: Architecture
-description: Technical architecture and design of DropOut Minecraft Launcher
----
-
-# Architecture
-
-DropOut is built with a modern tech stack designed for performance, security, and cross-platform compatibility.
-
-## Technology Stack
-
-### Backend (Rust)
-- **Framework**: Tauri v2
-- **Language**: Rust (Edition 2021)
-- **Async Runtime**: Tokio
-- **HTTP Client**: reqwest with native-tls
-
-### Frontend (Svelte)
-- **Framework**: Svelte 5 (with runes)
-- **Styling**: Tailwind CSS 4
-- **Build Tool**: Vite with Rolldown
-- **Package Manager**: pnpm
-
-### Documentation
-- **Framework**: Fumadocs with React Router v7
-- **Content**: MDX files
-- **Styling**: Tailwind CSS 4
-
-## System Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Frontend (Svelte 5)                   │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
-│  │  Stores  │  │Components│  │ UI Views │  │Particles│ │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
-│       │             │             │              │      │
-│       └─────────────┴─────────────┴──────────────┘      │
-│                          │                              │
-│                   Tauri Commands                        │
-│                    Events/Emitters                      │
-└──────────────────────────┬──────────────────────────────┘
-                           │
-┌──────────────────────────┴──────────────────────────────┐
-│                  Backend (Rust/Tauri)                    │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │               main.rs (Commands)                 │    │
-│  └──────────────┬──────────────────────────────────┘    │
-│                 │                                        │
-│  ┌──────────────┴───────────────────────────────┐       │
-│  │               Core Modules                   │       │
-│  │  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐  │       │
-│  │  │ Auth │ │Download│ │ Java │ │ Instance │  │       │
-│  │  └──────┘ └────────┘ └──────┘ └──────────┘  │       │
-│  │  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐  │       │
-│  │  │Fabric│ │ Forge  │ │Config│ │Manifest  │  │       │
-│  │  └──────┘ └────────┘ └──────┘ └──────────┘  │       │
-│  └──────────────────────────────────────────────┘       │
-│                                                          │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │                Utils & Helpers                   │    │
-│  │  • ZIP extraction  • Path utilities             │    │
-│  └─────────────────────────────────────────────────┘    │
-└──────────────────────────┬──────────────────────────────┘
-                           │
-                    External APIs
-                           │
-        ┌──────────────────┼──────────────────┐
-        │                  │                  │
-  ┌─────┴────┐      ┌──────┴─────┐    ┌──────┴─────┐
-  │  Mojang  │      │   Fabric   │    │   Forge    │
-  │   APIs   │      │    Meta    │    │   Maven    │
-  └──────────┘      └────────────┘    └────────────┘
-```
-
-## Core Components
-
-### Frontend State Management
-
-DropOut uses **Svelte 5 runes** for reactive state management:
-
-```typescript
-// stores/auth.svelte.ts
-export class AuthState {
-  currentAccount = $state<Account | null>(null);  // Reactive
-  isLoginModalOpen = $state(false);
-  
-  $effect(() => {  // Side effects
-    // Auto-runs when dependencies change
-  });
-}
-```
-
-**Key Stores:**
-- `auth.svelte.ts`: Authentication state and login flow
-- `settings.svelte.ts`: Launcher settings and Java detection
-- `game.svelte.ts`: Game running state and logs
-- `instances.svelte.ts`: Instance management
-- `ui.svelte.ts`: UI state (toasts, modals, active view)
-
-### Backend Architecture
-
-#### Command Pattern
-All Tauri commands follow this structure:
-
-```rust
-#[tauri::command]
-async fn command_name(
-    window: Window,
-    state: State<'_, SomeState>,
-    param: Type,
-) -> Result<ReturnType, String> {
-    emit_log!(window, "Status message");
-    // Async logic
-    Ok(result)
-}
-```
-
-#### Event Communication
-
-**Rust → Frontend (Progress Updates):**
-```rust
-window.emit("launcher-log", "Downloading...")?;
-window.emit("download-progress", progress_struct)?;
-```
-
-**Frontend → Rust (Commands):**
-```typescript
-import { invoke } from "@tauri-apps/api/core";
-const result = await invoke("start_game", { versionId: "1.20.4" });
-```
-
-### Core Modules
-
-#### Authentication (`core/auth.rs`)
-- **Microsoft OAuth 2.0**: Device Code Flow
-- **Offline Authentication**: Local UUID generation
-- **Token Management**: Refresh token storage and auto-refresh
-- **Xbox Live Integration**: Full authentication chain
-
-**Authentication Flow:**
-1. Device Code Request → MS Token
-2. Xbox Live Authentication
-3. XSTS Authorization
-4. Minecraft Token Exchange
-5. Profile Fetching
-
-#### Downloader (`core/downloader.rs`)
-- **Concurrent Downloads**: Configurable thread pool
-- **Resume Support**: `.part` and `.part.meta` files
-- **Multi-segment Downloads**: Large files split into chunks
-- **Checksum Verification**: SHA1/SHA256 validation
-- **Progress Tracking**: Real-time events to frontend
-
-#### Java Management (`core/java.rs`)
-- **Auto-detection**: Scans system paths
-- **Adoptium Integration**: Download JDK/JRE on-demand
-- **Catalog Caching**: 24-hour cache for version lists
-- **Installation**: Extracts to app data directory
-- **Cancellation**: Atomic flag for download cancellation
-
-#### Fabric Support (`core/fabric.rs`)
-- **Meta API Integration**: Fetch loader versions
-- **Profile Generation**: Creates version JSON
-- **Library Resolution**: Maven artifact handling
-
-#### Forge Support (`core/forge.rs`)
-- **Installer Execution**: Runs Forge installer
-- **Profile Parsing**: Extracts install profile
-- **Library Management**: Handles Forge-specific libraries
-
-#### Instance System (`core/instance.rs`)
-- **Isolation**: Separate directories per instance
-- **Configuration**: Per-instance settings
-- **Mod Management**: Instance-specific mods
-- **Version Locking**: Reproducible environments
-
-#### Version Management
-- **Manifest Parsing** (`manifest.rs`): Mojang version manifest
-- **Inheritance System** (`version_merge.rs`): Parent version merging
-- **Game Version** (`game_version.rs`): JSON parsing and validation
-- **Rules Engine** (`rules.rs`): OS/feature conditional logic
-
-### File Structure
-
-```
-~/.local/share/com.dropout.launcher/  (Linux)
-~/Library/Application Support/com.dropout.launcher/  (macOS)
-%APPDATA%/com.dropout.launcher/  (Windows)
-├── versions/
-│   └── <version_id>/
-│       ├── <version_id>.json
-│       ├── <version_id>.jar
-│       └── natives/
-├── libraries/
-│   └── <maven-path>/
-├── assets/
-│   ├── indexes/
-│   └── objects/
-├── instances/
-│   └── <instance_name>/
-│       ├── mods/
-│       ├── config/
-│       └── saves/
-├── java/
-│   └── <version>/
-├── config.json
-└── accounts.json
-```
-
-## Data Flow
-
-### Game Launch Sequence
-
-1. **Frontend**: User clicks "Launch Game"
-2. **Command**: `start_game(version_id)` invoked
-3. **Backend Processing**:
-   - Load version JSON (with inheritance)
-   - Resolve all libraries
-   - Download missing assets
-   - Extract native libraries
-   - Build classpath
-   - Construct JVM arguments
-   - Replace placeholders
-4. **Process Spawn**: Launch Java with arguments
-5. **Stream Logs**: Emit stdout/stderr to frontend
-6. **Monitor**: Track game process status
-
-### Download Flow
-
-1. **Queue Creation**: List of files to download
-2. **Concurrent Processing**: Semaphore-limited threads
-3. **Resume Check**: Verify existing `.part` files
-4. **Download**: Multi-segment for large files
-5. **Verification**: Checksum validation
-6. **Progress Events**: Real-time updates to UI
-7. **Completion**: Move from `.part` to final location
-
-### Authentication Flow
-
-1. **Device Code Request**: Get user code + device code
-2. **User Authorization**: User visits URL and enters code
-3. **Token Polling**: Frontend polls for completion
-4. **Token Exchange**: MS token → Xbox → XSTS → Minecraft
-5. **Profile Fetch**: Get username and UUID
-6. **Storage**: Save account with refresh token
-7. **Auto-refresh**: Background token refresh on expiry
-
-## Platform-Specific Considerations
-
-### Linux
-- Uses GTK WebView (`webkit2gtk`)
-- System Java detection from `/usr/lib/jvm`
-- Desktop file integration
-
-### macOS
-- Uses system WebKit
-- App bundle structure
-- Keychain integration for secure storage
-
-### Windows
-- Uses WebView2 runtime
-- Registry Java detection
-- MSI installer support
-- No console window in release builds
-
-## Performance Optimizations
-
-- **Concurrent Downloads**: Parallel asset/library downloads
-- **Lazy Loading**: Load version manifests on-demand
-- **Caching**: Java catalog, version manifests
-- **Native Code**: Rust for CPU-intensive operations
-- **Async I/O**: Tokio for non-blocking operations
-
-## Security Features
-
-- **Token Encryption**: Secure storage of auth tokens
-- **HTTPS Only**: All external API calls
-- **Checksum Validation**: File integrity verification
-- **Sandboxed Execution**: Tauri security model
-- **No Arbitrary Code**: No eval or dynamic code execution
-- 
cgit v1.2.3-70-g09d2

