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

> Explore the macro repository structure a Cargo workspace monorepo. Discover how 80+ Rust crates microservices and apps are organized in crates services apps and tooling directories.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: architecture
- Published: 2026-08-20

---

**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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/crate_name/src/lib.rs). Each crate may also export a binary via [`src/main.rs`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) for coding conventions and [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) that declares all members and shared metadata.

### The Root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) Workspace Definition

The top-level [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) defines the workspace with `resolver = "2"` and lists every crate and service in the `members` array:

```toml
[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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) with the crate name and workspace dependencies.
3. Include the new path in the workspace `members` array in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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:

```toml
[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:

```bash

# 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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md)** – Coding conventions for Rust and TypeScript.
- **[`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/services/email_service/Cargo.toml)** – Example individual service manifest.
- **[`crates/ai_usage/Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml)** and **Nix** guarantee reproducible local environments.
- New components are added by creating a directory, writing a [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) with the appropriate package name and dependencies, and append the directory path to the `members` array in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md).