# macro-inc/macro Project Structure: A Deep Dive into the Cargo Workspace Architecture

> Explore the macro-inc/macro project structure, a Cargo workspace with 80+ Rust crates. Discover how reusable libraries and microservices are organized and managed.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: deep-dive
- Published: 2026-08-15

---

**The macro-inc/macro repository is organized as a Cargo workspace containing over 80 Rust crates split between reusable core libraries in `crates/*` and standalone microservices in `services/*`, unified by shared dependencies defined in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml).**

The `macro-inc/macro` codebase represents a modern Rust monorepo designed for scalable cloud deployment. Understanding the macro project structure reveals a deliberate separation between business logic and service boundaries, enabling efficient development across AWS Lambda, Cloudflare Workers, and local tooling. The repository uses a workspace-wide `resolver = "2"` configuration to ensure consistent dependency resolution across all member crates.

## Workspace Configuration and Member Layout

The foundation of the macro project structure rests in the top-level [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml), which declares the workspace members and centralizes shared dependencies. This configuration eliminates version conflicts and enables incremental compilation across the entire codebase.

```toml
[workspace]
resolver = "2"

members = [
  "crates/activity",
  "crates/agent",
  "crates/ai_projections",
  "services/authentication_service",
  "services/document_storage_service",
  "services/email_service",
  "tooling/xtask",
]

```

All crates consume dependencies from a unified `[workspace.dependencies]` table, ensuring that critical libraries like `axum`, `sqlx`, `aws-sdk-*`, and `tracing` remain version-locked across every service and library.

## Core Libraries in the `crates/` Directory

The `crates/` directory houses **reusable business-logic libraries** that encapsulate domain functionality without assuming a specific runtime environment. These libraries expose public APIs through [`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs) files and enforce strict separation of concerns.

- **`crates/activity`** – Models user activity streams and events. Entry point: [[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)](https://github.com/macro-inc/macro/blob/main/crates/activity/src/lib.rs).

- **`crates/agent`** – Implements the internal AI-driven task execution engine. Entry point: [[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)](https://github.com/macro-inc/macro/blob/main/crates/agent/src/lib.rs).

- **`crates/search_service`** – Handles search indexing and retrieval logic using OpenSearch. Entry point: [[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)](https://github.com/macro-inc/macro/blob/main/crates/search_service/src/lib.rs).

- **`crates/macro_env_var`** – Provides a centralized wrapper for loading environment variables, enforcing the rule that `std::env::var` is never called directly in application code. Entry point: [[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)](https://github.com/macro-inc/macro/blob/main/crates/macro_env_var/src/lib.rs).

- **`crates/macro_event_broker`** – Manages internal event streaming via Amazon SQS, abstracting publish/subscribe patterns. Entry point: [[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)](https://github.com/macro-inc/macro/blob/main/crates/macro_event_broker/src/lib.rs).

## Service Binaries in the `services/` Directory

Unlike the reusable libraries, the `services/` directory contains **standalone binary targets** designed for specific deployment targets—AWS Lambda, Cloudflare Workers, or containerized environments. Each service includes a [`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs) entry point that wires together the core crates.

| Service | Entry Point | Runtime Role |
|---------|------------|--------------|
| **authentication_service** | [[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs) | JWT issuance, password validation, and SSO integration. |
| **document_storage_service** | [[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)](https://github.com/macro-inc/macro/blob/main/services/document_storage_service/src/main.rs) | Primary HTTP API for document upload, fetch, and versioning operations. |
| **email_service** | [[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)](https://github.com/macro-inc/macro/blob/main/services/email_service/src/main.rs) | Inbound/outbound email processing via Amazon SES and PostgreSQL persistence. |
| **search_processing_service** | [[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)](https://github.com/macro-inc/macro/blob/main/services/search_processing_service/src/main.rs) | Kafka event consumer that extracts searchable content and updates OpenSearch indices. |
| **sync-service** | [[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)](https://github.com/macro-inc/macro/blob/main/services/sync-service/src/main.rs) | Real-time WebSocket synchronisation worker deployed on Cloudflare Workers. |

## Tooling, Frontend, and Infrastructure

The macro project structure extends beyond Rust code to include comprehensive tooling and deployment configurations.

### Development Tooling

The **`tooling/xtask`** crate provides custom Cargo commands for CI automation, dependency graph generation, and code generation tasks. The entry point at [[`tooling/xtask/src/main.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/src/main.rs)](https://github.com/macro-inc/macro/blob/main/tooling/xtask/src/main.rs) exposes commands used by continuous integration pipelines to discover changed crates and execute migrations.

A top-level **Justfile** provides convenient shortcuts for common tasks, abstracting complex cargo invocations behind simple commands like `just build` and `just test`.

### Web Frontend

The **`apps/web/`** directory contains a TypeScript/React frontend that communicates with the Rust backend via generated GraphQL schemas. This separation allows the API and frontend to evolve independently while maintaining type safety through schema generation.

### Infrastructure and Deployment

- **`infra/`** – Pulumi stacks defining AWS and Cloudflare infrastructure as code.
- **`docker/`** – Dockerfiles and [`docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker-compose.yml) for local development databases (PostgreSQL, Redis).
- **`nix/`** – Nix flake definitions for reproducible development environments.

## Building and Running the Workspace

The unified workspace configuration enables standardized build commands across all services. Because every crate is declared in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml), Cargo treats the entire repository as a single dependency graph.

```bash

# Build every crate and service in the workspace

just build

# Run a specific service locally using its manifest path

cargo run --manifest-path services/document_storage_service/Cargo.toml

# Execute the full test suite including integration tests

just test

```

Local development requires the Docker Compose stack defined in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) to provide backing databases and caching layers.

## Summary

The macro project structure follows a deliberate monorepo architecture optimized for cloud-native Rust development:

- **Workspace-based organization** centralizes dependency management through the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml).
- **`crates/` directory** contains domain logic reusable across multiple deployment targets.
- **`services/` directory** houses standalone binaries for specific infrastructure (Lambda, Workers, containers).
- **Unified tooling** via `xtask` and Justfile standardizes CI and local development workflows.
- **Infrastructure-as-code** in `infra/` and `docker/` ensures consistent deployment from local machines to production.

## Frequently Asked Questions

### What is the difference between crates and services in macro-inc/macro?

**Crates** are library targets containing reusable business logic that compile to [`lib.rs`](https://github.com/macro-inc/macro/blob/main/lib.rs) artifacts, while **services** are binary targets with [`main.rs`](https://github.com/macro-inc/macro/blob/main/main.rs) entry points designed for specific deployment environments. Services depend on crates, but crates remain agnostic about their runtime context, allowing the same `activity` or `search_service` logic to run inside Lambda functions, Cloudflare Workers, or test harnesses.

### How does the workspace manage dependencies across 80+ crates?

The root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) defines a `[workspace.dependencies]` table that pins versions for shared libraries like `axum`, `sqlx`, and `aws-sdk-s3`. All member crates reference these dependencies using `workspace = true`, ensuring that upgrading a library version in one location propagates consistently across the entire codebase without version drift.

### What tooling is available for local development?

Developers use **Just** (via the `justfile`) for high-level task automation and **xtask** for repository-specific operations like migration generation. The [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) file spins up required PostgreSQL and Redis instances, while the **Nix** configuration provides reproducible shell environments. The `xtask` binary at [`tooling/xtask/src/main.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/src/main.rs) also exposes CI-specific commands for discovering which crates changed in a pull request.

### How are the services deployed in production?

Services deploy as specialized targets based on their architecture: AWS Lambda for event-driven processing (like `search_processing_service`), Cloudflare Workers for edge computing (like `sync-service`), and containerized binaries for long-running HTTP APIs (like `document_storage_service`). The `infra/` directory contains Pulumi TypeScript programs that define the IAM roles, VPC configurations, and API Gateway integrations required for each service's target platform.