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:
- Component Composition: Large components are broken down into smaller, reusable pieces
- 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 - Custom Hooks: Encapsulate complex logic for API calls, file operations, and state management
- 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 PropagationCore 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:
- Application Cache: In-memory caching for frequently accessed data
- Redis Cache: Distributed caching for API responses
- 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
Contributing Guidelines
Learn how to contribute to the project architecture
API Reference
Detailed API documentation for developers
Development Setup
Set up your development environment
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.