How the Macro Repository Is Structured: A Complete Guide to the Cargo Workspace Monorepo

The macro repository is a Cargo workspace monorepo containing more than 80 Rust crates, dozens of micro-services, and desktop apps organized across crates/, services/, apps/, and tooling/ directories.

The macro repository maintained by macro-inc is structured as a large Rust monorepo that uses a top-level Cargo.toml workspace to share dependencies across components. Understanding how the macro repository is structured helps developers navigate its three-tier hierarchy of reusable libraries, stand-alone services, and front-end applications.

The Top-Level Directory Layout

The repository root partitions code into four primary domains: core libraries, micro-services, end-user applications, and developer tooling.

Core Crates (crates/)

The crates/ directory houses pure Rust libraries that follow the convention crate_name/src/lib.rs. Each crate may also export a binary via src/main.rs when needed. Notable examples include crates/ai_usage, crates/graph, crates/comms_db_client, crates/activity, crates/agent, and crates/agent_fold.

Micro-Services (services/)

The services/ directory contains independently deployable back-ends compiled to binaries or Cloudflare workers. Each service owns its Cargo.toml and src/ implementation and is grouped by domain. Examples include services/document_storage_service, services/email_service, services/agent_harness_service, and services/authentication_service.

Tooling and Applications (tooling/ and apps/)

The tooling/ directory holds build-time helpers such as xtask, CLI utilities like seed_cli, and sandbox applications such as notification_sandbox. The apps/web/tauri/ path contains the desktop UI built with Tauri, including a TypeScript front-end under src-tauri/ and Rust native bindings.

Infrastructure and Documentation

Supporting directories at the repository root include:

• docker/ – Dockerfiles for each service and compose files that spin up PostgreSQL, Redis, OpenSearch, and other dependencies.
• docs/ – Human-readable design docs, including docs/STYLE_GUIDE.md for coding conventions and docs/RUNNING_LOCALLY.md for deployment guides.
• .github/ – CI/CD workflows and GitHub Actions configuration for automated testing, building, and deployment.
• nix/ and flake.nix – Nix expressions that define reproducible development environments and production builds.

Workspace Configuration and Build System

The macro repository is governed by a workspace-wide Cargo.toml that declares all members and shared metadata.

The Root Cargo.toml Workspace Definition

The top-level Cargo.toml defines the workspace with resolver = "2" and lists every crate and service in the members array:

[workspace]
resolver = "2"
members = [
  "crates/activity",
  "crates/agent",
  "crates/agent_fold",
  "...",
  "services/agent_harness_service",
  "services/authentication_service",
  "...",
  "tooling/xtask",
  "apps/web/tauri",
]

This file is the single source of truth for what is included in the macro workspace.

Task Automation with the justfile

High-level commands are orchestrated through the justfile at the repository root. Running just build compiles all services, just test executes every crate’s test suite, and just check runs linting and validation. The justfile also provides commands like just prepare_db for database migrations.

Local Development with Docker and Nix

Local infrastructure is managed via docker/docker-compose.yml, which provides PostgreSQL, Redis, OpenSearch, and the services themselves. For reproducible toolchains, the nix/ directory and flake.nix supply Nix shells that can be invoked with nix develop --command …. The nix/tauri-dev-shells.nix file specifically defines the environment for the Tauri desktop UI.

Adding a New Crate or Service

Contributors can extend the workspace by following four steps:

1. Create a new directory under crates/ or services/.
2. Add a Cargo.toml with the crate name and workspace dependencies.
3. Include the new path in the workspace members array in the root Cargo.toml.
4. Run just prepare_db if the crate touches the database, then just test to verify compilation.

A minimal new crate manifest looks like this:

[package]
name = "example_feature"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }

Running a Service Locally

To run a service such as document_storage_service locally, first start the backing stores and then build and execute the binary:

# Start the database stack

docker compose -f docker/docker-compose.yml up -d postgres redis opensearch

# Build the service

just build services/document_storage_service

# Run the binary from target/debug

cargo run -p document_storage_service -- --config ./config/local.toml

Key Files in the Macro Repository

• Cargo.toml – Workspace definition and shared dependencies located at the repository root.
• justfile – Task runner for build, test, check, and lint operations.
• docs/STYLE_GUIDE.md – Coding conventions for Rust and TypeScript.
• docker/docker-compose.yml – Local development orchestration for databases and search.
• nix/tauri-dev-shells.nix – Nix shell definition for the Tauri desktop UI.
• services/email_service/Cargo.toml – Example individual service manifest.
• crates/ai_usage/Cargo.toml – Example library crate manifest.

Summary

• The macro repository is a Cargo workspace monorepo that groups over 80 Rust crates and dozens of services under a single root Cargo.toml.
• Code is organized into crates/ for reusable libraries, services/ for deployable back-ends, and tooling//apps/ for developer utilities and the desktop UI.
• The justfile provides uniform commands for building and testing, while docker/docker-compose.yml and Nix guarantee reproducible local environments.
• New components are added by creating a directory, writing a Cargo.toml, and registering the path in the workspace members array.
• Services are run locally with docker compose for infrastructure and cargo run -p <service_name> for the binary itself.

Frequently Asked Questions

What build tools does the macro repository use?

The macro repository uses a root Cargo.toml to define the Rust workspace, a justfile for task automation, Docker Compose for local infrastructure, and Nix expressions for reproducible development shells. These tools work together so that commands like just build and just test work uniformly across every crate and service.

How do you add a new crate to the macro workspace?

Create a directory under crates/ or services/, add a Cargo.toml with the appropriate package name and dependencies, and append the directory path to the members array in the root Cargo.toml. Afterward, run just test to verify that the new crate compiles within the workspace.

What is the purpose of the services/ directory?

The services/ directory stores independently deployable micro-services that expose HTTP endpoints, Lambda handlers, or Cloudflare workers. Each service has its own Cargo.toml and src/ tree, enabling domain-specific binaries such as services/email_service and services/document_storage_service to be built and deployed separately.

How do you run a service locally in the macro repository?

First, start the required infrastructure with docker compose -f docker/docker-compose.yml up -d postgres redis opensearch. Then build the specific service with just build services/<service_name> and execute it via cargo run -p <service_name> -- --config ./config/local.toml. This workflow is documented in the root justfile and docs/RUNNING_LOCALLY.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}