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

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.

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, which declares the workspace members and centralizes shared dependencies. This configuration eliminates version conflicts and enables incremental compilation across the entire codebase.

[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 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/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/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/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/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/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 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/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/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/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/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/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) 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 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, Cargo treats the entire repository as a single dependency graph.

# 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 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.
• 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 artifacts, while services are binary targets with 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 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 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 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.

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