Turborepo & Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The mausVoice project is organized as a high-performance monorepo utilizing Turborepo and pnpm workspaces. This architecture enables a modular codebase where shared logic, types, and configurations are abstracted into dedicated packages, while the main application logic resides in the apps/ directory.
The repository follows a "Rust is the API, TypeScript is the Brain" philosophy. While the project contains native Rust components for audio capture and system interactions, the primary business logic and state management are centralized in TypeScript, managed via a unified build pipeline.
Sources: llms.txt:30-36, CLAUDE.md:14-16
Monorepo Layout
The repository is divided into two primary directories: apps/ for end-user applications and packages/ for shared libraries and configuration.
Directory Overview
| Path | Purpose | Key Technologies |
|---|---|---|
apps/desktop | Main Tauri desktop application | React, Zustand, Tauri (Rust) |
apps/docs | Authoritative documentation site | Astro, Starlight |
apps/windows-installer | Specialized Windows build target | Tauri |
packages/types | Centralized Zod schemas and TypeScript types | Zod, TypeScript |
packages/utilities | Shared helper functions | TypeScript, Vitest |
packages/voice-ai | AI-specific voice processing logic | TypeScript |
packages/desktop-native-apis | TypeScript wrappers for Tauri commands | TypeScript, Tauri |
packages/rust_transcription | Native sidecar for local transcription | Rust (Whisper.cpp) |
Sources: llms.txt:41-50, apps/desktop/package.json:44-50, packages/types/package.json:1-5
Workspace Dependency Graph
The following diagram illustrates how the main application consumes internal workspace packages. Shared packages like @maus-inc/types act as the foundation for the entire repository.
The application relies on internal packages defined in the monorepo's packages/ directory, ensuring consistency across the codebase.
Sources: apps/desktop/package.json:44-50, packages/utilities/package.json:23-25, packages/firemix/package.json:25-27
Build Pipeline & Task Orchestration
Turborepo is used to orchestrate tasks across the monorepo. It leverages a global cache and dependency awareness to ensure that packages are built in the correct order.
Pipeline Configuration (turbo.json)
The pipeline defines specific dependencies between tasks. For instance, check-types and test:evals depend on the completion of the build task to ensure that generated types and compiled artifacts are available.
{
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**", "dist/**", "lib/**"]
},
"check-types": {
"dependsOn": ["^build"]
},
"test": {
"dependsOn": ["^test"]
}
}
}
Sources: turbo.json:12-25
Critical Scripts
Development and maintenance are handled through root-level pnpm scripts that delegate to Turborepo.
pnpm run build: Executes the build task across all workspaces in topological order.pnpm run lint: Runs linting across all packages.pnpm run check-types: Performs TypeScript type checking.pnpm run test: Executes the test suite for all modules.pnpm gen:bindings: A specialized script that regenerates TypeScript bindings from Rust commands inpackages/desktop-native-apis.
Sources: package.json:4-11, packages/desktop-native-apis/package.json:12-16
Package Management
The repository uses pnpm with workspace protocol (workspace:*) to link internal dependencies. This ensures that changes in a shared package, such as @maus-inc/utilities, are immediately available to apps/desktop without requiring a registry publish.
Internal Dependency Linking
In apps/desktop/package.json, internal packages are declared as follows:
"dependencies": {
"@maus-inc/desktop-native-apis": "workspace:*",
"@maus-inc/types": "workspace:*",
"@maus-inc/utilities": "workspace:*",
"@repo/agent": "workspace:*"
}
Sources: apps/desktop/package.json:44-54
Dependency Resolution Sequence
When a developer modifies a shared TypeScript package, the following sequence must be followed for downstream consumers to reflect the changes:
Rebuilding the modified package is mandatory because downstream applications link to the compiled dist/ folder of the workspace package.
Sources: CLAUDE.md:15-16, packages/types/package.json:11-15
Environment Control
Turborepo is configured to track specific global environment variables. Any change in these variables will invalidate the build cache, ensuring that build artifacts remain consistent with the environment.
| Variable | Usage |
|---|---|
TAURI_PLATFORM | Determines the native target (macos, windows, linux) |
MAUSVOICE_DESKTOP_PLATFORM | Platform detection override for Node.js scripts |
FIRESTORE_EMULATOR_HOST | Used for local Firebase development |
Sources: turbo.json:4-10, apps/desktop/package.json:7-11
Conclusion
The Turborepo monorepo structure of mausVoice facilitates a highly modular development environment. By separating the "Brain" (TypeScript React/Zustand) from the "API" (Rust Tauri commands) and further subdividing the Brain into reusable packages, the project maintains high technical standards and scalability across different platforms.