Monorepo Workspace Patterns

Monorepo Workspace Patterns

Implements workspace-based monorepo architecture across multiple package ecosystems — npm, pnpm, yarn, Cargo, and uv — including dependency deduplication, cross-package references, build orchestration, and shared configuration management.

TL;DR Checklist

• Choose the right workspace tool for your language and build needs
• Configure root-level workspace declarations (pnpm-workspace.yaml, package.json workspaces, Cargo.toml [workspace], pyproject.toml workspace mode)
• Create packages with proper inter-package references (workspace:true, path:, file:)
• Set up dependency hoisting/deduplication to eliminate duplication
• Configure build orchestration (Turborepo or Nx) for caching and parallel execution
• Pin inter-package dependencies to workspace paths, not version ranges
• Document package boundaries and public APIs in each package's README
• Run type checking and linting from the root across all packages
• Never nest workspaces within workspaces
• Never manually symlink workspace packages — let the workspace tool manage it

When to Use

Use this skill when:

• Managing 3+ related packages that share code, dependencies, or configuration (e.g., a frontend app, shared UI library, and API client)
• Multiple teams work on tightly coupled services where atomic commits across packages are required
• Shared internal libraries need consistent versioning and instant cross-package reference without publishing
• You want build caching, parallel execution, and task orchestration across all packages
• You need dependency deduplication to reduce disk usage and install times across many packages

When NOT to Use

Avoid this skill for:

• Single package projects — A single package.json or Cargo.toml is simpler and faster
• Loosely coupled independent services — If teams deploy independently with no shared code, use separate repositories
• Very large repos (1000+ packages) — Consider a polyrepo strategy or splitting into focused monorepos
• Quick prototypes — The configuration overhead of a monorepo outweighs benefits for throwaway code

Core Workflow

Step 1: Select Workspace Tool

Choose the workspace tool based on your language, build speed requirements, and developer count. Each ecosystem has native workspace support plus third-party orchestration tools.

Decision Matrix:

Decision rules:

• Python projects → uv workspace mode (native, fast, single lockfile)
• TypeScript/JS with 3+ packages → pnpm workspaces + Turborepo (best performance and strictness)
• Rust projects → Cargo workspaces (native, battle-tested)
• Polyglot repo (Python + TS + Rust) → Turborepo as the orchestration layer with language-native workspace tools underneath

Step 2: Configure Workspace Root

Set up the root-level configuration. Each ecosystem uses a different declaration file.

pnpm workspaces — Create pnpm-workspace.yaml at repository root:

# pnpm-workspace.yaml
# Packages that are members of this workspace
packages:
  - 'apps/*'          # All apps under apps/ directory
  - 'packages/*'      # All shared packages under packages/
  - 'libs/**'         # Nested libraries (use ** for deeper nesting)
  # Explicitly exclude directories that should never be workspace members
  '!apps/e2e-tests'   # Exclude end-to-end test apps from workspace resolution

# Strict mode: pnpm will fail if a peer dependency is not satisfied
strictPeerDependencies: true

# Hoist all common dependencies to root node_modules
hoist-pattern:
  - '*react*'
  - '*typescript*'
  - '@types/*'

# Packages that must NEVER be hoisted (usually because they have native bindings)
nohoist:
  - '**/tsup'
  - '**/esbuild'
  - '**/@swc/**'

# Lockfile settings
lockfileFlags:
  auto-install-peers: true

npm workspaces — Configure in root package.json:

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*",
    "!apps/e2e-tests"
  ],
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test --parallel",
    "lint": "turbo run lint",
    "type-check": "turbo run type-check"
  },
  "devDependencies": {
    "turbo": "^2.4.0"
  }
}

Cargo workspaces — Configure in root Cargo.toml:

# Root Cargo.toml — the workspace manifest
[workspace]
members = [
    "crates/*",
    "bin/*",
]
# Exclude packages that are standalone binaries not part of the library hierarchy
exclude = ["crates/integration-tests"]

# Resolver: use edition 2021 (required for Rust 2021+ features)
resolver = "2"

# Define default-package members activated by default when running cargo commands
default-members = [
    "crates/core",
    "crates/api",
]

# Shared dependency versions in one place — all crates use ^1.2 from here
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
anyhow = "1.0"
tonic = "0.12"

# Override a single crate's version for testing or emergency patches
[workspace.dependencies.overrides]
tokio = "=1.42.0"  # Pin exact version for debugging

# Configure build optimization profiles shared across all workspace members
[profile.release]
lto = "fat"
codegen-units = 1
strip = true

[profile.dev]
split-debuginfo = "unpacked"

uv workspace mode (Python) — Configure in root pyproject.toml:

# Root pyproject.toml — uv workspace mode requires [tool.uv.workspace]
[project]
name = "my-python-monorepo"
version = "0.1.0"
description = "Monorepo for Python packages using uv workspace mode"
requires-python = ">=3.12"
readme = "README.md"
license = { text = "MIT" }

[tool.uv.workspace]
members = [
    "packages/core",
    "packages/sdk",
    "packages/cli",
    "apps/*",
]
exclude = [
    "tests/integration",
]

# Shared dev dependencies for all workspace members
[tool.uv]
dev-dependencies = [
    "pytest>=8.3",
    "pytest-asyncio>=0.24",
    "ruff>=0.8",
    "mypy>=1.14",
    "hypothesis>=6.122",
]

# Global overrides — useful when a dependency has issues across the workspace
[tool.uv.sources]
core = { workspace = true }
sdk = { workspace = true }
cli = { workspace = true }

# uv task runner configuration — replaces makefiles and scripts for build orchestration
[tool.uv.tasks]
test = "pytest"
lint = "ruff check packages/ apps/"
format = "ruff format packages/ apps/"
type-check = "mypy packages/ --strict"
build-docs = { cmd = "mkdocs build", cwd = "packages/docs" }

Step 3: Create Package Members

Scaffold each package with proper inter-package dependency references. Each workspace member must declare itself as a workspace dependency when referencing sibling packages.

pnpm workspace reference using workspace: protocol:

// packages/shared-types/package.json — A shared TypeScript types package
{
  "name": "@myorg/shared-types",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc --project tsconfig.build.json",
    "type-check": "tsc --noEmit",
    "clean": "rm -rf dist"
  },
  "devDependencies": {
    "typescript": "^5.7.0"
  }
}

// apps/web/package.json — Depends on shared-types via workspace protocol
{
  "name": "@myorg/web",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    // ✅ CORRECT: workspace protocol resolves to local package, no version needed
    "@myorg/shared-types": "workspace:*",
    // ✅ CORRECT: for specific version range within workspace
    "@myorg/api-client": "workspace:^1.2.0",
    "next": "^15.1.0",
    "react": "^19.0.0"
  },
  "devDependencies": {
    "@myorg/eslint-config": "workspace:*",
    "typescript": "^5.7.0"
  }
}

Cargo workspace reference using [workspace.dependencies]:

# crates/core/Cargo.toml — Core library with no internal dependencies
[package]
name = "myorg-core"
version = "0.1.0"
edition = "2021"
description = "Core domain types and shared logic"

[dependencies]
serde = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
anyhow = { workspace = true }

# crates/api/Cargo.toml — API layer depending on core via path reference
[package]
name = "myorg-api"
version = "0.1.0"
edition = "2021"

[dependencies]
myorg-core = { path = "../core" }  # Direct path to sibling crate
serde = { workspace = true }
tokio = { workspace = true }
tonic = { workspace = true }
tracing = { workspace = true }
anyhow = { workspace = true }

# Conditional compilation — only include these dependencies for certain features
[dependencies.tower-http]
optional = true
version = "0.6"
features = ["trace", "cors"]

[features]
default = []
tracing-subscriber = ["dep:tracing-subscriber"]
# Platform-specific feature flags
linux-only = []

uv workspace reference using [tool.uv.sources]:

# packages/sdk/pyproject.toml — SDK package depending on core
[project]
name = "myorg-sdk"
version = "0.1.0"
description = "Python SDK for interacting with the platform"
requires-python = ">=3.12"
dependencies = [
    "httpx>=0.28",
    "pydantic>=2.10",
]

[tool.uv.sources]
# ✅ CORRECT: workspace reference — resolves to packages/core in the workspace
myorg-core = { workspace = true }

# packages/cli/pyproject.toml — CLI app depending on both core and sdk
[project]
name = "myorg-cli"
version = "0.1.0"
description = "Command-line interface for the platform"
requires-python = ">=3.12"

dependencies = [
    "click>=8.1",
    "rich>=13.9",
    "pydantic-settings>=2.7",
]

[tool.uv.sources]
myorg-core  = { workspace = true }
myorg-sdk   = { workspace = true }

# Optional dependencies for the CLI only
[project.optional-dependencies]
dev = [
    "pytest>=8.3",
    "pytest-mock>=3.14",
]

Step 4: Deduplicate Dependencies

Configure dependency hoisting and deduplication to share common dependencies and avoid duplication across workspace members.

pnpm hoisting configuration:

# pnpm-workspace.yaml — Extended hoisting rules
packages:
  - 'apps/*'
  - 'packages/*'

hoist-pattern:
  # Hoist React ecosystem to root — shared by almost every frontend package
  - '*react*'
  - '*@types/react*'
  # Hoist TypeScript tooling
  - 'typescript'
  - '@typescript-eslint/*'
  - 'eslint*'
  # Hoist test frameworks (shared across packages)
  - 'vitest'
  - '@vitest/*'
  - 'jest'
  # Hoist common linting/formatting tools
  - 'prettier'
  - 'tsup'
  - 'esbuild'

# Never hoist packages with native binaries — they must resolve locally per-package
nohoist:
  # Rust toolchain — always resolves locally to avoid platform conflicts
  - '**/node-sass'
  - '**/canvas'
  - '**/sharp'
  # Build tools with platform-specific binaries
  - '**/@swc/**'
  - 'esbuild'
  # Vite plugins that depend on specific Vite versions
  - '**/vite-plugin-*'

# Resolve peer dependencies automatically — prevents "missing peer" errors
auto-install-peers: true
# Remove hoisted packages from package-lock after install for cleanliness
deduplicate-hoisted: true

pnpm peer dependency enforcement:

// packages/ui-components/package.json — Declare explicit peer deps
{
  "name": "@myorg/ui-components",
  "version": "2.0.0",
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0"
  },
  // ✅ Critical: pnpm will enforce these are satisfied by the consuming package
  // Without this, pnpm will fail installation if react is not a direct dep of apps/web
  "peerDependenciesMeta": {
    "react-dom": { "optional": true }
  }
}

Cargo workspace dependency sharing:

# Root Cargo.toml — Shared dependencies defined once, used by all crates
[workspace]
members = ["crates/*"]
resolver = "2"

[workspace.dependencies]
# Define versions in one place — prevents version drift between crates
serde = { version = "1.0", features = ["derive", "rc"] }
tokio = { version = "1", features = ["full", "tracing"] }
anyhow = "1.0"
thiserror = "2.0"
async-trait = "0.1"

# Use workspace = true in each crate to reference shared deps
# Example from crates/api/Cargo.toml:
# [dependencies]
# tokio = { workspace = true }       # Gets version 1.x with features: full, tracing
# serde = { workspace = true }       # Gets version 1.0 with features: derive, rc
# myorg-core = { path = "../core" } # Direct path to sibling crate

Step 5: Configure Build Orchestration

Set up Turborepo or Nx for task caching, parallel execution, and cross-package dependency management.

Turborepo pipeline configuration:

// turbo.json — Task pipeline definitions with dependency graph and caching
{
  "$schema": "https://turbo.build/schema.json",
  // Global environment variables that all tasks inherit
  "globalEnv": ["NODE_ENV", "CI", "DATABASE_URL"],
  // Tasks that must run from the workspace root (not per-package)
  "globalDependencies": [
    "**/.env.*local",
    "**/tsconfig*.json",
    "pnpm-lock.yaml",
    ".nvmrc"
  ],
  // Tasks that are outputs and should be excluded from caching if changed
  "globalPassThroughEnv": ["AWS_ACCESS_KEY_ID", "GITHUB_TOKEN"],
  // Task definitions — the core of Turborepo configuration
  "tasks": {
    // Build task: runs tsc, no upstream dependencies, output is dist/
    "build": {
      "dependsOn": ["^build"],         // Run each package's build before this one
      "inputs": ["src/**", "*.tsconfig*json"], // Files that affect the build
      "outputs": ["dist/**"],           // Cache if these files exist and haven't changed
      "outputLogs": "new-only"          // Only show new output, not cached builds
    },

    // Dev task: hot-reload mode, no caching (always run fresh)
    "dev": {
      "dependsOn": ["^build"],         // Depends on sibling packages being built
      "cache": false,                   // Never cache dev mode — always run
      "persistent": true               // Keep running (long-lived process)
    },

    // Test task: runs tests for a package, depends on its build
    "test": {
      "dependsOn": ["build"],          // Must build before testing
      "inputs": ["src/**", "tests/**"],
      "outputs": [],                    // No outputs — always re-run if source changes
      "env": ["CI"],                   // Pass CI env var for headless mode
      "outputLogs": "new-only"
    },

    // Type-check: run type checking without emitting, depends on build
    "type-check": {
      "dependsOn": [],                 // No upstream deps — can start immediately
      "inputs": ["src/**", "*.tsconfig*json"],
      "outputs": []
    },

    // Lint: fast task, cache the result, no upstream deps
    "lint": {
      "cache": true,
      "inputs": ["src/**", ".eslintrc*", "eslint.config.*"]
    },

    // Format: same as lint but runs prettier/ruff
    "format": {
      "cache": false,                 // Formatting is not cacheable by nature
      "persistent": true
    },

    // Clean: must run before rebuild, removes all dist folders
    "clean": {
      "cache": false
    },

    // Full pipeline: clean + build + test in sequence across workspace
    "//full-ci": {
      "dependsOn": ["^build", "test"]
    }
  }
}

Turborepo root package.json scripts:

// packages/web/package.json — Application-level turbo script
{
  "scripts": {
    // Turbo will run build across all packages that declare a build task
    "build:all": "turbo run build",
    // Run dev with hot reload, rebuilding dependent packages automatically
    "dev:all": "turbo run dev --parallel",
    // Run tests in parallel across all packages
    "test:all": "turbo run test --parallel",
    // Full CI pipeline: type-check → lint → build → test (sequential dependency chain)
    "ci": "turbo run type-check lint build test",
    // Preview a single package's build with output from dependent packages
    "preview-build": "turbo run build --filter=@myorg/web..."
  }
}

Nx workspace configuration:

// nx.json — Nx task orchestration (alternative to Turborepo)
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "namedInputs": {
    // Reusable input sets for tasks — referenced in project.json targets
    "default": ["{projectRoot}/**/*"],
    "production": [
      "default",
      "!{projectRoot}/tests/**/*",
      "!{projectRoot}/.eslintrc.json",
      "!{projectRoot}/tsconfig.test.json"
    ],
    "sharedConfig": ["{workspaceRoot}/nx.json", "{workspaceRoot}/tsconfig.base.json"]
  },

  // Target defaults — apply these settings to matching targets across all projects
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],        // Depends on upstream builds
      "inputs": ["production", "^production"],
      "cache": true,
      "outputs": ["{projectRoot}/dist"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },

  // Parallelism settings for CI
  "parallel": 3,

  // Cache directory location
  "cacheDirectory": ".nx/cache"
}

Nx project configuration (per-package):

// packages/api/project.json — Individual project definition in Nx
{
  "name": "@myorg/api",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "packages/api/src",
  "tags": ["scope:api", "type:service"],

  "targets": {
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/packages/api",
        "format": ["cjs"],
        "bundle": false,
        "generatePackageJson": true
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "options": {
        "jestConfig": "packages/api/jest.config.js"
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint"
    }
  }
}

Implementation Patterns

Pattern 1: pnpm Workspace with Strict Peer Dependency Enforcement

Use this pattern when you have shared UI or utility packages consumed by multiple apps. The workspace:* protocol combined with strict peer dependency enforcement ensures all apps use a single version of React and shared dependencies.

# pnpm-workspace.yaml — Strict workspace with peer dependency management
packages:
  - 'apps/*'
  - 'packages/*'

# Enforce that peer dependencies are always satisfied — pnpm will fail if not
strictPeerDependencies: true

# Hoist React ecosystem for deduplication
hoist-pattern:
  - '*react*'
  - '@types/react*'
  - 'next'

# Never hoist packages with native bindings or platform-specific binaries
nohoist:
  - '**/@swc/**'
  - '**/esbuild**'
  - '**/node-sass**'
  - '**/sharp**'

// packages/design-system/package.json — Shared UI library with peer deps
{
  "name": "@myorg/design-system",
  "version": "3.2.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "sideEffects": false,

  // Peer dependencies: apps MUST install these themselves
  // pnpm will fail installation if an app doesn't have react as a direct dependency
  "peerDependencies": {
    "react": "^18.2.0 || ^19.0.0",
    "react-dom": "^18.2.0 || ^19.0.0"
  },

  // Internal development dependencies (not published)
  "devDependencies": {
    "@storybook/react": "^8.4.0",
    "typescript": "^5.7.0"
  },

  // Dependencies that ARE bundled into the published package
  "dependencies": {
    "clsx": "^2.1.0",
    "tailwind-merge": "^2.6.0"
  }
}

// packages/design-system/src/index.ts — Public API surface
/** @module @myorg/design-system */

export { Button, type ButtonProps } from './components/Button';
export { Input, type InputProps } from './components/Input';
export { Modal, type ModalProps } from './components/Modal';
export { ThemeProvider, useTheme, type ThemeContext } from './providers/ThemeProvider';
export { createTheme, type DesignTokens } from './theme/createTheme';

// Internal modules — NOT exported (not part of the public API)
// These are implementation details and may change without notice

// apps/web/package.json — Consuming the design system
{
  "name": "@myorg/web",
  "private": true,
  "dependencies": {
    // ✅ workspace:* resolves to local @myorg/design-system, no publish needed
    "@myorg/design-system": "workspace:*",
    "@myorg/shared-types": "workspace:*",

    // ✅ React MUST be a direct dependency (peer dep of design-system)
    "react": "^19.0.0",
    "react-dom": "^19.0.0",

    // Regular npm packages
    "next": "^15.1.0"
  },
  "devDependencies": {
    "@myorg/eslint-config": "workspace:*",
    "@myorg/tsconfig": "workspace:*"
  }
}

Pattern 2: Cross-Package TypeScript References in a Monorepo

Use this pattern when you need IDE autocomplete and type checking to work across packages as if they were all in one project. The key is using references in tsconfig with path aliases.

// Root tsconfig.json — Workspace-level base configuration
{
  "compilerOptions": {
    // Shared settings for all workspace packages
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,

    // Path aliases resolved at workspace root level
    "baseUrl": ".",
    "paths": {
      "@myorg/*": ["packages/*/src/index.ts"],
      "@myorg/ui/*": ["packages/design-system/src/components/*"],
      "@myorg/types/*": ["packages/shared-types/src/*"]
    }
  },
  // Reference projects — enables project-referenced builds for incremental compilation
  "references": [
    { "path": "packages/shared-types" },
    { "path": "packages/design-system" },
    { "path": "packages/api-client" },
    { "path": "apps/web" }
  ],
  // Exclude test files and build output from all package-level references
  "exclude": ["node_modules", "**/dist", "**/*.test.ts"]
}

// packages/shared-types/tsconfig.json — Package-specific tsconfig extends root
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    // Override base settings for this package only
    "outDir": "./dist",
    "rootDir": "./src",
    // Emit declaration files for consumers of this package
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["src/**/*.test.ts"]
}

// apps/web/tsconfig.json — Application tsconfig references library packages
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "outDir": "./dist",
    "rootDir": ".",
    // Path overrides for the app's own files
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "references": [
    { "path": "../packages/shared-types" },
    { "path": "../packages/design-system" },
    { "path": "../packages/api-client" }
  ],
  "include": ["src/**/*", "next-env.d.ts"],
  "exclude": ["node_modules", "dist"]
}

// apps/web/src/pages/index.tsx — Cross-package imports with full type safety
import { Button, Modal, ThemeProvider, useTheme } from '@myorg/design-system';
import { ApiResponse, type User } from '@myorg/shared-types';
import { createApiClient } from '@myorg/api-client';

// TypeScript resolves types across packages via project references
async function fetchUser(userId: string): Promise<ApiResponse<User>> {
  const client = createApiClient({
    baseUrl: process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3001',
  });

  return client.get(`/users/${userId}`);
}

// Type safety is maintained across package boundaries
export default function HomePage() {
  const theme = useTheme();

  return (
    <ThemeProvider value={theme}>
      <Button variant="primary" => fetchUser('123')}>
        Load User
      </Button>
      {/* TypeScript knows ButtonProps has 'variant' because it comes from @myorg/design-system */}
    </ThemeProvider>
  );
}

Pattern 3: Cargo Workspace with Conditional Compilation (Features, Platform-Specific Code)

Use this pattern when building a Rust monorepo where crates share common functionality but need feature-flagged behavior and platform-specific implementations.

# Root Cargo.toml — Workspace manifest with shared features and dependencies
[workspace]
members = [
    "crates/core",       # Core domain types (no internal deps)
    "crates/storage",    # Storage layer (depends on core, conditional on feature)
    "crates/api",        # HTTP/gRPC API (depends on storage)
    "crates/cli",        # CLI binary (depends on api + core)
]
resolver = "2"

# Shared dependencies defined once at workspace level
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"
tracing = "0.1"

# Shared feature flags for the entire workspace
[workspace.package]
version = "0.3.0"
edition = "2021"
license = "MIT"
authors = ["Engineering <eng@example.com>"]
repository = "https://github.com/example/myorg-rust"

# Profiles shared across all crates
[profile.release]
lto = true
codegen-units = 1
strip = true
opt-level = 3

[profile.dev]
split-debuginfo = "unpacked"
debug = 2

# crates/storage/Cargo.toml — Feature-gated storage backends
[package]
name = "myorg-storage"
version.workspace = true
edition.workspace = true

[dependencies]
myorg-core = { path = "../core" }
serde = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
async-trait = "0.1"

# Conditional dependencies — only compiled when the feature is enabled
[dependencies.rocksdb]
optional = true
version = "0.22"

[dependencies.sqlx]
optional = true
version = "0.8"
features = ["postgres", "runtime-tokio-rustls", "migrate"]

# Features: consumers enable one storage backend at a time
[features]
default = ["memory-store"]
memory-store = []            # In-memory store (always available)
rocksdb = ["dep:rocksdb"]    # Enable RocksDB backend
sqlx-pg = ["dep:sqlx"]       # Enable PostgreSQL via SQLx

# Platform-specific code — only compiled on Linux
[target.'cfg(target_os = "linux")'.dependencies]
nix = { version = "0.29", optional = true, features = ["fs", "mman"] }

[features.linux-advanced]
linux-advanced = ["dep:nix"]

// crates/storage/src/lib.rs — Feature-gated storage backends with trait abstraction
use myorg_core::domain::{Entity, EntityId};

/// Trait that all storage backends must implement
#[async_trait::async_trait]
pub trait StorageBackend: Send + Sync {
    /// Save an entity to the storage backend
    async fn save(&mut self, entity: &Entity) -> Result<(), StorageError>;

    /// Retrieve an entity by its ID
    async fn get(&self, id: EntityId) -> Result<Option<Entity>, StorageError>;

    /// List all entities with optional pagination
    async fn list(
        &self,
        limit: u32,
        offset: u32,
    ) -> Result<Vec<Entity>, StorageError>;
}

// ─── In-Memory Backend (always compiled) ──────────────────────────────

#[derive(Default)]
pub struct MemoryStorage {
    data: std::collections::HashMap<EntityId, Entity>,
}

#[async_trait::async_trait]
impl StorageBackend for MemoryStorage {
    async fn save(&mut self, entity: &Entity) -> Result<(), StorageError> {
        tracing::debug!(entity_id = %entity.id, "saving entity to memory");
        self.data.insert(entity.id.clone(), entity.clone());
        Ok(())
    }

    async fn get(&self, id: EntityId) -> Result<Option<Entity>, StorageError> {
        Ok(self.data.get(&id).cloned())
    }

    async fn list(&self, limit: u32, offset: u32) -> Result<Vec<Entity>, StorageError> {
        let entities: Vec<Entity> = self.data.values()
            .skip(offset as usize)
            .take(limit as usize)
            .cloned()
            .collect();
        Ok(entities)
    }
}

// ─── RocksDB Backend (only compiled when `rocksdb` feature is enabled) ─

#[cfg(feature = "rocksdb")]
pub struct RocksDbStorage {
    db: rocksdb::DB,
}

#[cfg(feature = "rocksdb")]
#[async_trait::async_trait]
impl StorageBackend for RocksDbStorage {
    async fn save(&mut self, entity: &Entity) -> Result<(), StorageError> {
        let key = serde_json::to_string(&entity.id)?;
        let value = serde_json::to_string(entity)?;
        self.db.put(key.as_bytes(), value.as_bytes())?;
        Ok(())
    }

    async fn get(&self, id: EntityId) -> Result<Option<Entity>, StorageError> {
        let key = serde_json::to_string(&id)?;
        match self.db.get(key.as_bytes())? {
            Some(value) => {
                let entity: Entity = serde_json::from_slice(&value)?;
                Ok(Some(entity))
            }
            None => Ok(None),
        }
    }

    // ... list implementation for RocksDB ...
}

// ─── Factory function — returns the appropriate backend based on config ─

#[derive(Debug, Clone)]
pub struct StorageConfig {
    pub backend: StorageBackendType,
}

#[derive(Debug, Clone)]
pub enum StorageBackendType {
    Memory,
    #[cfg(feature = "rocksdb")]
    RocksDb { path: std::path::PathBuf },
    #[cfg(feature = "sqlx-pg")]
    SqlxPg { connection_string: String },
}

impl StorageConfig {
    pub fn build(self) -> Result<Box<dyn StorageBackend>, StorageError> {
        match self.backend {
            StorageBackendType::Memory => Ok(Box::new(MemoryStorage::default())),
            #[cfg(feature = "rocksdb")]
            StorageBackendType::RocksDb { path } => {
                let db = rocksdb::DB::open_default(&path)?;
                Ok(Box::new(RocksDbStorage { db }))
            }
            #[cfg(feature = "sqlx-pg")]
            StorageBackendType::SqlxPg { connection_string } => {
                // SQLx pool initialization (simplified)
                todo!("Initialize PostgreSQL storage backend")
            }
        }
    }
}

// ─── Platform-specific optimization: Linux memory mapping ──────────────

#[cfg(target_os = "linux")]
fn optimize_file_io_for_linux(file_size: u64) -> std::io::Result<()> {
    use nix::fcntl::{mmap, MMapProt, MMapFlags};
    use nix::sys::mman::MapAdvice;
    // Linux-specific memory-mapped I/O optimization for large storage files
    // ... implementation ...
    Ok(())
}

Pattern 4: Python uv Workspace Mode for Shared Venv and Lockfile

Use this pattern for Python monorepos where multiple packages share a single virtual environment and lockfile. This is the modern approach replacing poetry and pip-tools for monorepo dependency management.

# Root pyproject.toml — uv workspace configuration with shared venv
[project]
name = "myorg-monorepo"
version = "0.1.0"
description = "Monorepo for Python packages using uv workspace mode"
requires-python = ">=3.12"
readme = "README.md"

[tool.uv.workspace]
members = [
    "packages/core",
    "packages/sdk",
    "packages/cli",
    "apps/api-server",
]
exclude = [
    "scripts/*",       # Build/CI scripts are not packages
    "tools/*",         # Development tools are standalone
]

# Workspace-level shared dev dependencies applied to ALL members
[tool.uv]
dev-dependencies = [
    "pytest>=8.3,<9",
    "pytest-asyncio>=0.24,<1",
    "pytest-cov>=6.0,<7",
    "hypothesis>=6.122,<7",
    "ruff>=0.8,<1",
    "mypy>=1.14,<2",
    "types-requests>=2.32,<3",
]

# Global source overrides for workspace packages — enables cross-package deps
[tool.uv.sources]
myorg-core  = { workspace = true }
myorg-sdk   = { workspace = true }
myorg-cli   = { workspace = true }

# packages/core/pyproject.toml — Core library (base package with no internal deps)
[project]
name = "myorg-core"
version = "0.2.0"
description = "Core domain types, models, and shared utilities"
requires-python = ">=3.12"
dependencies = [
    "pydantic>=2.10,<3",
    "structlog>=25.1,<26",
]

[project.optional-dependencies]
asyncio = ["aiosqlite>=0.20,<1"]
testing = ["hypothesis>=6.122,<7"]

# Build configuration using hatchling (recommended for uv workspaces)
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.metadata]
allow-direct-references = true  # Required for workspace resolution

# Package discovery — which directories contain source code
[tool.hatch.build.targets.wheel]
packages = ["src/myorg/core"]

# MyPy type checking configuration
[tool.mypy]
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

# packages/sdk/pyproject.toml — SDK package depending on core via workspace
[project]
name = "myorg-sdk"
version = "0.2.0"
description = "Python SDK for interacting with the myorg platform API"
requires-python = ">=3.12"

dependencies = [
    "httpx>=0.28,<1",
    "pydantic>=2.10,<3",
    "myorg-core",  # ← No version needed; uv resolves to workspace member
]

[project.optional-dependencies]
auth = ["cryptography>=44.0,<45"]
asyncio = ["anyio>=4.8,<5"]

[project.scripts]
sdk-docs = "myorg.sdk.cli:main"  # Entry point for a CLI command from the SDK

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

# Workspace source resolution — tells uv this depends on the workspace member
[tool.uv.sources]
myorg-core = { workspace = true }

# packages/cli/pyproject.toml — CLI application depending on both core and sdk
[project]
name = "myorg-cli"
version = "0.2.0"
description = "Command-line interface for myorg"
requires-python = ">=3.12"

dependencies = [
    "click>=8.1,<9",
    "rich>=13.9,<14",
    "pydantic-settings>=2.7,<3",
    "myorg-core",   # Workspace resolution to packages/core
    "myorg-sdk",    # Workspace resolution to packages/sdk
]

[project.scripts]
myorg = "myorg.cli:main"   # Main CLI entry point
myorg-admin = "myorg.cli.admin:main"  # Admin subcommand entry point

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv.sources]
myorg-core  = { workspace = true }
myorg-sdk   = { workspace = true }

# apps/api-server/pyproject.toml — API server using all workspace packages
[project]
name = "myorg-api-server"
version = "0.1.0"
description = "Production API server for myorg"
requires-python = ">=3.12"

dependencies = [
    "fastapi>=0.115,<1",
    "uvicorn[standard]>=0.34,<1",
    "sqlalchemy>=2.0,<3",
    "myorg-core",     # Workspace resolution
    "myorg-sdk",      # Workspace resolution
]

[tool.uv.sources]
myorg-core  = { workspace = true }
myorg-sdk   = { workspace = true }

[tool.uv.tasks]
# Task runner replaces Makefile — runs from workspace root
serve = "uvicorn apps.api_server.main:app --reload"
test = "pytest apps/ packages/"
lint = "ruff check apps/ packages/"
type-check = "mypy packages/ apps/"

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]

Pattern 5: Turborepo Pipeline with Task Dependencies and Caching

Use this pattern for monorepos requiring build caching, task orchestration, and selective execution. This configuration supports incremental builds, parallel test execution, and filtered runs.

// turbo.json — Production-ready pipeline configuration
{
  "$schema": "https://turbo.build/schema.json",

  // Environment variables inherited by all tasks
  "globalEnv": [
    "NODE_ENV",
    "CI",
    "NEXT_PUBLIC_API_URL",
    "DATABASE_URL"
  ],

  // Files whose changes invalidate ALL caches — treat as full-rebuild triggers
  "globalDependencies": [
    "**/.env.*local",
    "**/tsconfig*.json",
    "pnpm-lock.yaml",
    "turbo.json",
    ".nvmrc"
  ],

  // Environment variables that are passed through but don't affect caching
  "globalPassThroughEnv": [
    "AWS_ACCESS_KEY_ID",
    "GITHUB_TOKEN",
    "NPM_TOKEN",
    "VERCEL_TOKEN"
  ],

  // Task definitions — the core pipeline configuration
  "tasks": {
    // Build: incremental compilation with dependency graph
    "build": {
      "dependsOn": ["^build"],                    // Run all upstream builds first
      "inputs": [                                  // Files that affect build output
        "src/**",
        "*.tsconfig*json",
        "globals.css",
        "!src/**/*.test.ts",
        "!src/**/*.test.tsx"
      ],
      "outputs": [                                 // Cache if these exist and are unchanged
        "dist/**",
        ".next/**",
        ".output/**",
        "build/**"
      ],
      "outputLogs": "new-only",                   // Only show new build output
      "cache": true
    },

    // Type check: fast, no output artifacts, depends on upstream builds
    "type-check": {
      "dependsOn": [],                            // No upstream — starts immediately
      "inputs": [
        "src/**",
        "*.tsconfig*json"
      ],
      "outputs": [],                              // No outputs to cache
      "outputLogs": "new-only",
      "cache": true
    },

    // Test: isolated per-package, depends on build, no caching for speed
    "test": {
      "dependsOn": ["build"],                     // Must build before testing
      "inputs": [
        "src/**",
        "tests/**"
      ],
      "outputs": [],
      "outputLogs": "new-only",
      "cache": false                              // Disable cache for tests (always re-run)
    },

    // Test with coverage: generates artifacts that should be cached
    "test:coverage": {
      "dependsOn": ["build"],
      "inputs": ["src/**", "tests/**"],
      "outputs": ["coverage/**"],
      "outputLogs": "new-only",
      "cache": true
    },

    // Lint: deterministic, fast, fully cacheable
    "lint": {
      "dependsOn": [],
      "inputs": [
        "src/**",
        ".eslintrc*",
        "eslint.config.*"
      ],
      "outputs": [],
      "outputLogs": "new-only",
      "cache": true
    },

    // Dev: long-running, no caching, depends on upstream builds
    "dev": {
      "dependsOn": ["^build"],
      "cache": false,                             // Never cache dev mode
      "persistent": true                          // Keep process running
    },

    // Clean: removes build artifacts, not cacheable
    "clean": {
      "cache": false
    },

    // Preview single-package build with upstream outputs visible
    "preview": {
      "dependsOn": ["^build"],
      "outputLogs": "full"                        // Show all upstream output in preview mode
    }
  }
}

**Turborepo CLI

…(truncated)