Deadlock Mod Manager
Developer Documentation

Architecture Overview

System architecture and design decisions of Deadlock Mod Manager

For changes to discovery, downloads, installation, or profiles, read the Domain Model first. It defines identity and ownership across the catalog, IPC, and local file operations.

High-Level Architecture

System Overview

Core Components

1. Desktop Application (Tauri + React)

  • Frontend: React-based UI with TypeScript
  • Backend: Rust-based Tauri application for system integration
  • Communication: IPC between frontend and backend layers
  • File Management: Direct file system access for mod installation

2. API Service (Bun + Hono)

  • Data Synchronization: Fetches mod data from GameBanana
  • Caching Layer: Redis for performance optimization
  • Database: PostgreSQL for persistent storage
  • Background Jobs: Queue-based processing for heavy operations

3. Mirror Service (Bun + Hono)

  • File Caching: S3-backed caching layer for mod downloads
  • Performance Optimization: Reduces load on GameBanana API
  • Bandwidth Savings: Serves frequently accessed files from cache
  • Background Workers: Automated validation and cleanup processes

For detailed information, see the Mirror Service Documentation.

4. Shared Packages

  • Database Schema: Centralized data models using Drizzle ORM
  • Logging: Structured logging across all services
  • Common Utilities: Shared business logic and types

Desktop Application Architecture

External plugin runtime

The desktop's plugins Cargo feature is off by default and gates the runtime dependency, worker entry point, host setup, IPC commands, and frame protocol. The desktop dev script enables it automatically (pnpm desktop:dev); release builds require --features plugins explicitly. The frontend checks get_runtime_bootstrap.features.plugins before exposing plugin settings or routes. In supported builds, the Experimental Plugins setting resumes the host; turning it off stops workers and revokes sessions without changing saved per-plugin preferences or grants.

The plugin runtime module (packages/plugin-runtime, Rust crate dmm-plugin-runtime) owns external package validation, grants, lifecycle, WASM worker supervision, plugin storage, and staged artifacts. Its interface centers on PluginHost; registry records and worker protocol details remain private to the implementation.

The profile deployment seam uses ProfileAdapter. The desktop adapter calls the existing mod manager, game-file guards, and profile manifest operations; runtime tests use a filesystem adapter. This keeps game-visible installed addons under desktop Rust ownership while allowing runtime tests to run without Tauri.

The frame adapter stays in apps/desktop/src-tauri/src/external_plugins. It serves plugin interfaces to sandboxed iframes on the app's /ext/<id> page, with their CSP, and gets a view descriptor and authorized assets from the runtime instead of reading registry records or package paths. Frames have no IPC; the app page relays their postMessage calls with external_plugins_frame_call. Plugin-author SDKs and the external Creator Workspace Bridge package remain independent of the desktop build.

Frontend Architecture (React)

Key Design Patterns:

  1. Component Composition: Large components are broken down into smaller, reusable pieces
  2. Zustand store: Persisted application state lives in the store at apps/desktop/src/lib/store/, composed from domain slices. React Query owns remote server data, and theme state comes from a React context provider
  3. Custom Hooks: Encapsulate complex logic for API calls, file operations, and state management
  4. Separation of Concerns: UI components separate from business logic

Backend Architecture (Tauri/Rust)

Desktop Backend (Rust)
├── File System Management
│   ├── Mod Installation
│   ├── File Validation
│   ├── Backup/Restore
│   └── Path Resolution
├── System Integration
│   ├── Game Detection
│   ├── Steam Integration
│   ├── OS-Specific Features
│   └── Security Permissions
├── API Communication
│   ├── HTTP Client
│   ├── Download Manager
│   ├── Progress Tracking
│   └── Error Handling
└── IPC Layer
    ├── Command Handlers
    ├── Event Emission
    ├── State Synchronization
    └── Error Propagation

Core Responsibilities:

  • File Operations: Safe mod installation and management
  • System Integration: Game detection and path management
  • Network Operations: API communication and file downloads
  • Security: Secure file operations with user permissions

API Service Architecture

Service Layer Design

Layer Responsibilities:

HTTP Layer

  • Request/response handling
  • CORS configuration
  • Rate limiting
  • Request logging

Router Layer

  • Route definition and organization
  • Path parameter extraction
  • Route-specific middleware

Handler Layer

  • Request validation
  • Response formatting
  • Error handling
  • Authentication checks

Service Layer

  • Business logic implementation
  • External API integration
  • Background job scheduling
  • Cache management

Repository Layer

  • Database query abstraction
  • Data transformation
  • Transaction management
  • Query optimization

Desktop Catalog Data Flow

Mirror Service Architecture

The mirror service acts as a caching layer for mod file downloads, improving performance and reducing load on external APIs.

High-Level Architecture

Key Features:

  • Smart Caching: Automatically caches mod files on first download
  • Stream-Through Upload: Files are streamed to client while uploading to S3
  • Stale Detection: Background workers validate file integrity
  • Automatic Cleanup: Removes unused files based on retention policy
  • Metrics Tracking: Cache hit rates, bandwidth savings, and download statistics

For complete technical details and integration patterns, see the Mirror Service Documentation.

Data Architecture

Database Schema Design

Refer to the drizzle schema for the database schema.

Design Principles:

  • Normalized Structure: Reduces data redundancy
  • Foreign Key Constraints: Ensures data integrity
  • Indexing Strategy: Optimized for common query patterns
  • Account data: User records store names, email addresses and avatar URLs; sessions can store IP addresses and user agents. See Privacy and Network Activity for what each service receives

Caching Strategy

Cache Layers:

  1. Application Cache: In-memory caching for frequently accessed data
  2. Redis Cache: Distributed caching for API responses
  3. Browser Cache: Client-side caching for UI resources

Security Architecture

Desktop Application Security

File System Security

  • Sandboxed Operations: All file operations go through Tauri's secure API
  • Permission Model: Explicit permissions for file system access
  • Path Validation: All paths validated before operations
  • Backup Strategy: Automatic backups before destructive operations

Network Security

  • HTTPS Only: All network requests use TLS encryption
  • Request Validation: All API responses validated before use
  • Rate Limiting: Protection against abuse

Architecture Questions?

If you have questions about architectural decisions or want to propose improvements, please join our Discord community or create an issue for discussion.

On this page