Project Structure
Understanding the Deadlock Mod Manager codebase organization and architecture
The pnpm monorepo separates applications in apps/, shared packages in packages/, and tooling in tools/.
Overview
deadlock-modmanager/
├── apps/ # Applications
│ ├── api/ # Backend API service
│ ├── bot/ # Discord bot
│ ├── desktop/ # Main Tauri desktop app
│ ├── docs/ # Documentation site
│ ├── lockdex/ # Lockdex service
│ └── www/ # Marketing website
├── packages/ # Shared packages
│ ├── common/ # Common utilities
│ ├── database/ # Database schema & client
│ ├── distributed-lock/ # Utilities for distributed locking
│ ├── feature-flags/ # Feature flag system
│ ├── instrumentation/ # Observability tools
│ ├── logging/ # Structured logging
│ ├── queue/ # Queue management
│ ├── shared/ # Shared types & utilities
│ └── vpk-parser/ # VPK file parsing (Rust)
├── tools/ # Development tools
│ └── typescript/ # Shared TypeScript configs
├── .agents/ # Shared agent reference material and skills
└── .cursor/ # Cursor MCP and editor settingsApplications (apps/)
Desktop App (apps/desktop/)
The main Tauri-based desktop application - the primary user interface for the mod manager.
apps/desktop/
├── src/ # React frontend source
│ ├── components/ # React components (118 files)
│ ├── pages/ # Application pages/routes
│ ├── hooks/ # Custom React hooks (32 files)
│ ├── contexts/ # React contexts
│ ├── lib/ # Utility libraries (19 files)
│ ├── locales/ # Internationalization files
│ └── types/ # TypeScript type definitions
├── src-tauri/ # Rust backend
│ ├── src/ # Rust source code (18 files)
│ ├── icons/ # Application icons
│ ├── capabilities/ # Tauri security capabilities
│ └── tauri.conf.json # Tauri configuration
├── public/ # Static assets
└── dist/ # Built applicationKey Technologies:
- Frontend: React 19 + TypeScript + Tailwind CSS v4
- Backend: Tauri v2 with Rust
- State Management: Zustand store (
src/lib/store/) for persisted state, React Query for remote data - Styling: Tailwind CSS v4 with custom design system
- Build: Vite for frontend, Cargo for Rust
API Service (apps/api/)
Backend API service that synchronizes mod data from GameBanana and serves it to clients.
apps/api/
├── src/
│ ├── config/ # Application configuration
│ ├── handlers/ # Request handlers (2 files)
│ ├── lib/ # Utility libraries (8 files)
│ ├── processors/ # Data processing logic (2 files)
│ ├── providers/ # External service providers (4 files)
│ ├── routers/ # API route definitions (14 files)
│ ├── services/ # Business logic services (9 files)
│ ├── types/ # TypeScript type definitions (2 files)
│ └── validation/ # Request validation schemas (6 files)
└── dist/ # Built applicationKey Technologies:
- Runtime: Bun for high performance
- Framework: Hono for lightweight HTTP server
- Validation: Zod for type-safe validation
- Database: PostgreSQL with Drizzle ORM
- Observability: Structured logging with Sentry
Discord Bot (apps/bot/)
Discord bot for community integration and notifications. Built with Sapphire and Discord.js.
apps/bot/
├── src/
│ ├── commands/ # Discord slash commands
│ ├── listeners/ # Event listeners
│ ├── services/ # Bot services (4 files)
│ └── lib/ # Utility libraries (9 files)
└── dist/ # Built applicationKey Technologies:
- Runtime: Bun
- Library: Discord.js
- Database: Shared database package
Documentation Site (apps/docs/)
This documentation site built with Fumadocs and Next.js.
apps/docs/
├── content/docs/ # Documentation content
│ ├── using-mod-manager/ # Player guide
│ ├── modding/ # Modding guides
│ ├── plugins/ # Plugin docs
│ ├── developer-docs/ # Developer documentation
│ ├── api/ # Generated API reference
│ └── index.mdx # Documentation homepage
├── src/
│ ├── app/ # Next.js app router pages
│ └── lib/ # Utility libraries
├── public/ # Static assets
└── wrangler.jsonc # Cloudflare Workers configKey Technologies:
- Framework: Next.js 16 with App Router, built as a static export (
output: "export") - Documentation: Fumadocs for MDX processing
- Styling: Tailwind CSS
- Content: MDX for documentation pages
- Hosting: Cloudflare Workers static assets, built and deployed by Workers Builds on every push to
main
Keep the docs statically exportable
The site is served as plain files, so it can't use middleware, rewrites, or
route handlers that run per request. Every dynamic route needs
generateStaticParams, and other route handlers need export const dynamic = "force-static". Run pnpm --filter @deadlock-mods/docs build to check: the
export fails on anything that can't be prerendered.
Other Applications
Lockdex Service (apps/lockdex/)
Service for managing Deadlock game data and indexing.
Marketing Website (apps/www/)
Public-facing website for project information and downloads.
Shared Packages (packages/)
Plugin runtime (packages/plugin-runtime/)
dmm-plugin-runtime is a standalone Rust crate for external plugin packages,
grants, lifecycle, storage, artifacts, and supervised WASM workers. Its profile
deployment interface is implemented by a desktop adapter. Serving plugin
frames and the Tauri commands remain in apps/desktop/src-tauri/src/external_plugins/.
Run runtime tests independently with
cargo test --manifest-path packages/plugin-runtime/Cargo.toml.
Database Package (packages/database/)
Centralized database schema and client using Drizzle ORM.
packages/database/
├── src/
│ ├── schema/ # Database schema definitions
│ ├── migrations/ # Database migrations
│ ├── seed/ # Database seeding
│ └── client.ts # Database client configuration
└── drizzle.config.ts # Drizzle configurationFeatures:
- PostgreSQL with type-safe queries
- Automatic migration generation
- Seed data for development
- Connection pooling and optimization
Logging Package (packages/logging/)
Structured logging system with context support and Sentry integration.
packages/logging/
├── src/
│ ├── logger.ts # Core logger implementation
│ ├── context.ts # Async context support
│ ├── formatters/ # Log formatters
│ └── types.ts # Type definitions
└── README.md # Usage documentationFeatures:
- Environment-aware formatting
- Request-scoped context
- Error tracking integration
- Type-safe log methods
Shared Utilities (packages/shared/)
Common utilities and type definitions used across applications.
packages/shared/
├── src/
│ ├── types/ # Shared TypeScript types
│ ├── utils/ # Utility functions
│ ├── constants.ts # Application constants
│ └── validators/ # Shared validation schemas
└── CHANGELOG.mdVPK Parser (packages/vpk-parser/)
Rust-based package for parsing Valve VPK (Valve Pak) files with TypeScript bindings.
packages/vpk-parser/
├── src/ # TypeScript bindings
├── src-rs/ # Rust implementation (4 files)
├── test/ # Test files
├── Cargo.toml # Rust dependencies
└── package.json # npm package configurationFeatures:
- Native Rust performance for file parsing
- TypeScript bindings through Bun FFI (
src/ffi.ts), which loads the Rust library fromtarget/release - Comprehensive VPK format support
- Memory-efficient streaming parsing
Queue System (packages/queue/)
Queue management system for background job processing.
packages/queue/
├── src/
│ ├── queues/ # Queue implementations
│ ├── workers/ # Worker processes
│ ├── jobs/ # Job definitions
│ └── scheduler.ts # Job scheduling
└── README.mdOther Packages
packages/common/: Common error handling and utilitiespackages/distributed-lock/: Distributed locking mechanismspackages/feature-flags/: Feature flag managementpackages/instrumentation/: Observability and monitoring tools
Development Tools (tools/)
TypeScript Configuration (tools/typescript/)
Shared TypeScript configurations for consistent typing across the monorepo.
tools/typescript/
├── base.json # Base TypeScript config
├── nextjs.json # Next.js specific config
└── package.jsonConfiguration Files
Root Level Configuration
pnpm-workspace.yaml: Workspace configuration for pnpmturbo.json: Turborepo configuration for build optimization.oxlintrc.json/.oxfmtrc.json: oxlint and oxfmt configurationlefthook.yml: Git hooks for pre-commit checkscompose.yml: Docker Compose for local development.gitignore: Version control ignore patterns
Agent Instructions and Skills
AGENTS.md is the shared entry point for project conventions and task-specific guidance. CLAUDE.md imports it for Claude Code. Detailed references and workflows live in .agents/:
.agents/
├── context/ # Coding, error handling, Tauri, product, and design
└── skills/ # Verification, changesets, reviews, and other workflowspnpm install links the canonical skills into .claude/skills/; run pnpm skills:link after changing the skill set. .cursor/ contains editor and MCP configuration, not project conventions.
Key Technologies & Patterns
Frontend Technologies
- React 18: Modern React with hooks and concurrent features
- TypeScript: Strict typing throughout the codebase
- Tailwind CSS v4: Utility-first styling with custom configuration
- Vite: Fast development and building
- Tauri v2: Native desktop capabilities with web technologies
Backend Technologies
- Bun: High-performance JavaScript runtime
- Hono: Lightweight web framework
- PostgreSQL: Robust relational database
- Drizzle ORM: Type-safe database queries
- Redis: Caching and session storage
Development Tools
- pnpm: Fast, disk space efficient package manager
- Turborepo: Monorepo build system with caching
- oxlint / oxfmt: Linting and formatting
- Lefthook: Git hooks for quality assurance
- Docker: Containerized development environment
Architectural Patterns
Monorepo Organization
The project uses several patterns for effective monorepo management:
- Clear Separation: Apps vs packages vs tools
- Dependency Direction: Apps depend on packages, not vice versa
- Shared Configurations: TypeScript, linting, and formatting configs
- Build Orchestration: Turborepo for efficient builds and caching
Type Safety
The project emphasizes type safety:
- No
anytypes: Strict TypeScript configuration - Branded types: Enhanced type safety for domain objects
- Schema validation: Zod for runtime type checking
- Database types: Generated from schema definitions
Error Handling
Consistent error handling patterns:
- Structured errors: Common error types and handling
- Logging integration: All errors are properly logged
- User-friendly messages: Meaningful error messages for users
- Development aids: Detailed error information in development
Package Dependencies
Dependency Flow
Key Dependencies
Each package has specific responsibilities:
- Apps: Consume packages, provide user interfaces
- Packages: Provide shared functionality, business logic
- Tools: Development and build-time utilities
Working with the Structure
Adding New Features
- Determine scope: App-specific or shared functionality?
- Choose location: Appropriate app or package directory
- Follow patterns: Use existing patterns for consistency
- Update dependencies: Add to appropriate package.json files
Adding New Packages
- Create package directory: Under
packages/ - Initialize package.json: With appropriate metadata
- Add to workspace: Update
pnpm-workspace.yamlif needed - Export properly: Ensure clean public API
Refactoring
- Identify shared code: Look for duplication across apps
- Extract to packages: Move shared code to appropriate packages
- Update imports: Use workspace references (
@deadlock-mods/*) - Test thoroughly: Ensure all apps still work correctly
Next Steps
Architecture Guide
Deep dive into system architecture and design decisions
Contributing Guidelines
Learn how to contribute effectively to the project
API Reference
Detailed API documentation for developers
Questions About Structure?
If you have questions about the project structure or need help understanding how components fit together, feel free to ask in our Discord community or create an issue on GitHub.