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

> Explore the Macro Rust monorepo project structure. Discover 7 core components including apps, services, crates, packages, infrastructure, Docker, and tooling for efficient development.

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

---

**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)](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)](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)](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)](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)](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:

```bash

# Build all services

just build

# Run tests

just test

# Start a specific service

just run services/email_service

```

Direct Cargo execution also works:

```bash
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

```rust
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

```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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/AGENTS.md). Add database migrations to the shared `macro_db_client` crate, update the workspace [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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.