Macro Project Structure Explained: 7 Core Components of a Rust Microservices Workspace

The Macro project is a large Rust-based monorepo organized into 7 main layers: apps/ for frontend clients, services/ for 42 deployable microservices, crates/ for 167 reusable Rust libraries, packages/ for shared TypeScript code, and supporting directories for infrastructure, Docker, Nix, and tooling.

This architecture powers Macro's AI-native workspace platform, where every email, message, and document becomes searchable through bidirectional @-linking. Understanding the project structure is essential for contributors, operators, and anyone integrating with the Macro Cloud Platform (MCP) API.

---

Repository Layout Overview

The top-level structure is documented in [README.md](https://github.com/macro-inc/macro/blob/main/README.md#L13-L25) and follows a workspace-based organization common in large Rust projects:

macro/
├── apps/            # SolidJS client (web, Tauri desktop, mobile) and docs site

├── services/        # 42 deployable services, workers, and Lambda handlers

├── crates/          # 167 reusable Rust libraries

├── packages/        # Shared TypeScript code

├── infra/           # Pulumi definitions for cloud infrastructure

├── docker/          # Docker-Compose stack for local development

├── nix/             # Pin-locked dev shells and build inputs

└── tooling/         # Repo scripts, code generators, and helper utilities

Each directory serves a distinct purpose in the development lifecycle, from local development to production deployment.

---

Frontend Layer: The apps/ Directory

The apps/ directory contains all user-facing applications built with SolidJS. This unified frontend stack supports multiple deployment targets from a shared codebase.

• apps/web/ — Primary web application
• apps/docs/ — Documentation site

The web client is the entry point for user actions: sending emails, posting messages, creating tasks, and managing documents. These actions trigger API calls to the appropriate backend services.

---

Service Layer: 42 Deployable Microservices in services/

The services/ directory contains the core business logic, organized into functional categories. All services share MacroDB (PostgreSQL) and communicate via HTTP APIs.

Core Storage Services

These services own the primary database tables and serve as the data foundation:

Service	Responsibility	Source Path
document-storage-service	Main document storage API	services/document_storage_service/
document-cognition-service	Document analysis & processing	services/document_cognition_service/
search_service	Full-text search across documents	services/search_service/
static_file_service	Static file serving (S3, CDN)	services/static_file_service/

Processing Services

Background and transformation workflows:

• convert_service — Document format conversion (PDF, DOCX, etc.)
• document-text-extractor — Text extraction from uploaded files
• search_processing_service — Indexing and updating the OpenSearch backend
• notification_service — User notifications (push, email, in-app)

Communication Services

Real-time collaboration and CRM functionality:

• email_service — Unified multi-account inbox with AI-assisted drafting and email-to-CRM sync
• connection_gateway — WebSocket gateway for live updates
• contacts_service — Contact & company management

Infrastructure Services

Platform-level capabilities:

• authentication_service — User authentication & session handling
• worker_trigger — Triggers background workers (AWS ECS tasks, Lambda)
• mcp_auth_proxy — Proxy for Macro Cloud Platform authentication
• mcp_service — Core MCP API for external agent integration

All services follow hexagonal architecture as documented in [AGENTS.md](https://github.com/macro-inc/macro/blob/main/AGENTS.md): inbound adapters → core domain logic → outbound adapters.

---

Library Layer: 167 Reusable crates/

The crates/ directory contains domain-specific Rust libraries consumed by services and frontends:

• crates/macro_db_client — SQLx-based database client with offline-validated queries
• crates/email_api_client — Email service client
• crates/graphql_* — GraphQL schema and client libraries
• crates/worker-rs-otel — Observability utilities for background workers

These crates enforce clean boundaries between domain concepts and enable code reuse across the 42 services.

---

TypeScript Layer: Shared packages/

Cross-platform JavaScript/TypeScript code lives in packages/:

• packages/mcp-client — Official TypeScript wrapper for the MCP HTTP API
• packages/collaboration — Real-time collaboration primitives
• packages/lexical-core — Lexical editor integration
• packages/loro-mirror — CRDT synchronization utilities

---

Infrastructure and Operations

infra/ — Cloud Infrastructure

Pulumi TypeScript definitions for AWS resources, networking, and service deployments. The main entry point is [infra/pulumi/main.ts](https://github.com/macro-inc/macro/blob/main/infra/pulumi/main.ts).

docker/ — Local Development

Docker Compose stack for running the full system locally: [docker/docker-compose.yml](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml).

nix/ — Reproducible Builds

Pin-locked Nix shells and build inputs ensure consistent development environments across machines.

tooling/ — Development Automation

Scripts, code generators, and helper utilities. The xtask pattern is implemented in [tooling/xtask/src/main.rs](https://github.com/macro-inc/macro/blob/main/tooling/xtask/src/main.rs) for custom Cargo commands.

---

How the Components Interact

Understanding the Macro project structure requires seeing how layers connect during operation:

1. User initiates action → apps/web SolidJS client
2. API call → Relevant service (email_service, document_storage_service, etc.)
3. Database write → MacroDB (PostgreSQL)
4. Background processing → Webhook or DB trigger activates processing service
5. Search/index update → search_processing_service updates OpenSearch
6. Real-time sync → notification_service pushes via connection_gateway WebSocket
7. Agent access → External AI agents call mcp_service for full read/write access

This flow ensures every piece of context remains searchable and AI-accessible.

---

Running and Developing Locally

Build the entire workspace and run specific services:

# Build all services

just build

# Run tests

just test

# Start a specific service

just run services/email_service

Direct Cargo execution also works:

cargo run -p email_service

Just commands are defined in the root justfile, with per-service targets generated from the workspace structure.

---

Code Examples

Creating Documents with the Rust Client

use macro_db_client::DocumentClient;
use uuid::Uuid;

#[tokio::main]
async fn main() -> Result<(), macro_db_client::Error> {
    let client = DocumentClient::new().await?;
    let doc_id = Uuid::new_v4();
    client.create_document(doc_id, "My new doc", "markdown content").await?;
    println!("Document created: {doc_id}");
    Ok(())
}

The DocumentClient resides in crates/document-storage-service and uses SQLx offline-validated queries compiled at build time.

Using the MCP API from TypeScript

import { createMcpClient } from "@macro/mcp";

const client = createMcpClient({
  baseUrl: "https://mcp-server.macro.com/mcp",
  token: "YOUR_MCP_TOKEN",
});

await client.tasks.create({
  title: "Follow-up on email",
  description: "Check with the sales team",
});

This client mirrors the Rust service APIs and provides type-safe access to workspace data.

---

Summary

• Seven-layer structure: apps/, services/, crates/, packages/, infra/, docker/, nix/, tooling/
• 42 services organized by function: storage, processing, communication, infrastructure
• 167 crates provide reusable Rust domain logic with SQLx offline validation
• Hexagonal architecture enforced across all services per AGENTS.md
• Shared PostgreSQL (MacroDB) with OpenSearch for full-text search
• MCP API enables external AI agents to read/write workspace data
• SolidJS frontend with Tauri for cross-platform desktop deployment

---

Frequently Asked Questions

What programming language is the Macro project primarily written in?

Rust, with TypeScript for infrastructure (Pulumi) and shared packages. The 42 services and 167 crates form a Rust-native backend, while SolidJS powers the frontend applications.

How do I add a new service to the Macro project structure?

Create a new crate in services/ following the hexagonal pattern documented in AGENTS.md. Add database migrations to the shared macro_db_client crate, update the workspace Cargo.toml, and define Pulumi resources in infra/ for deployment.

What is the purpose of the Macro Cloud Platform (MCP) service?

The mcp_service exposes a public HTTP API that external AI agents use to interact with the workspace. It provides authenticated read/write access to documents, emails, tasks, and contacts—enabling automation and integrations while maintaining the same data consistency guarantees as the web client.

How does search work across the Macro project structure?

Documents are indexed by search_processing_service, which consumes database changes and updates an OpenSearch cluster. The search_service provides the query API, while real-time updates flow through the WebSocket connection_gateway to keep client indexes synchronized.

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