# What Is Macro Inc and What Does the macro Repository Do? Architecture, Services, and Code Examples

> Discover Macro Inc. and the macro repository. Learn about its Rust-centric microservice architecture for real-time collaboration. Explore services and code examples.

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

---

**Macro Inc. is a venture-backed startup whose open-source `macro` repository powers a cloud-native, real-time collaboration platform built as a Rust-centric microservice architecture.**

If you are asking what is Macro Inc and what does the macro repository do, the answer is a single open-source monorepo that drives a real-time document collaboration ecosystem. Available at `macro-inc/macro` on GitHub, the repository serves as the engine behind Macro Inc.'s web application, providing everything from CRDT-based editing and WebSocket messaging to document storage and full-text search. Written primarily in Rust and organized as a microservice architecture, it includes a React and Tauri frontend alongside supporting services for email, notifications, and authentication.

## Architecture of the macro Repository

The `macro` repository follows a layered microservice design where each crate handles a specific domain. According to the `macro-inc/macro` source code, the workspace is declared in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml), and all services run as Docker containers orchestrated by [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml), with optional deployment as AWS Lambda functions.

### Core Storage and Processing Services

At the foundation, the platform manages document blobs and extracts meaningful data from them:

- **`document-storage-service`** — Provides an HTTP API for uploading, retrieving, and versioning document blobs stored in Amazon S3. The request handlers live in [`crates/document_storage_service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document_storage_service/src/lib.rs), while the client interface is defined in [`crates/document_storage_service/src/client.rs`](https://github.com/macro-inc/macro/blob/main/crates/document_storage_service/src/client.rs).
- **`document-text-extractor`** — Parses PDF and DOCX files to extract raw text. Its pipeline is implemented in [`crates/document_text_extractor/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document_text_extractor/src/lib.rs).
- **`convert_service`** — Handles format conversions between document types.
- **`search_processing_service`** — Indexes extracted content into an OpenSearch cluster.

### Search, Communication, and Infrastructure

Above storage sits the search layer and the messaging fabric:

- **`search_service`** — Exposes full-text search APIs, query builders, and OpenSearch client wrappers. The thin wrapper around the OpenSearch HTTP API lives in [`crates/opensearch_client/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/opensearch_client/src/lib.rs), and the fluent query builder is implemented in [`crates/opensearch_query_builder/src/builder.rs`](https://github.com/macro-inc/macro/blob/main/crates/opensearch_query_builder/src/builder.rs).
- **`email_service`** and **`notification_service`** — Manage inbound and outbound email and push notifications.
- **`connection_gateway`** — Maintains WebSocket connections for real-time messaging.
- **`authentication_service`** — Handles user authentication via FusionAuth.
- **`contacts_service`** — Manages user contact lists.
- **`macro_db_client`** — The centralized PostgreSQL data-access layer using SQLx queries and migrations, located in [`crates/macro_db_client/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/lib.rs).

### Real-Time Collaboration and Frontend

The user-facing layer is built on a CRDT engine and a modern web stack:

- **`packages/collaboration`** — Includes `loro-mirror` and `lexical-core`, which implement CRDT-based real-time editing, cursor and selection sync, and text-diff handling. The Loro CRDT implementation resides in [`packages/loro-mirror/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/packages/loro-mirror/src/lib.rs).
- **`apps/web`** — A React and Tauri application that serves as the browser and desktop UI. It sets up service clients and routing from [`apps/web/src/lib/core/app.tsx`](https://github.com/macro-inc/macro/blob/main/apps/web/src/lib/core/app.tsx), and consumes generated SDKs defined in [`packages/sdk/README.md`](https://github.com/macro-inc/macro/blob/main/packages/sdk/README.md) to communicate with backend services.

## Data Stores in the macro Platform

Macro Inc.'s architecture relies on four primary data stores:

- **MacroDB** — A PostgreSQL database holding core entities such as users, projects, messages, and document metadata.
- **OpenSearch** — An Elasticsearch-compatible cluster used for full-text indexing and search queries.
- **Amazon S3** — Object storage for raw document files managed by the storage service.
- **Redis** — A caching layer for session data and real-time ephemeral state.

## Development Workflow for the macro Repository

Developers interact with the codebase through the Nix-powered build system and the `just` task runner. The entry points are defined in the `justfile` at the repository root.

1. **Setup** — Run `just setup_macrodb` and `just setup_test_envs` to initialize local dependencies.
2. **Build** — Execute `just build` to compile all Rust crates, or `just build_lambdas` to produce AWS Lambda artifacts.
3. **Test** — Run `just test` to execute unit and integration tests against a locally running PostgreSQL instance.
4. **Run** — Launch the full stack with `just stack up`, which spins up all databases and services in Docker. The web UI becomes reachable at `http://localhost:8090/app/`.

For detailed steps, see [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md).

## Code Examples from the macro Repository

### Uploading a Document via the Storage Service

The following Rust snippet demonstrates how to create a document using the `DocumentStorageClient`. It relies on `MacroDb` for database initialization and uploads a local PDF file:

```rust
use macro_db_client::db::MacroDb;
use document_storage_service::client::DocumentStorageClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialise a DB connection (uses macros for env-var handling)
    let db = MacroDb::connect().await?;
    let client = DocumentStorageClient::new(&db)?;

    // Upload a PDF (the file is read from the local filesystem)
    let file_path = std::path::Path::new("example.pdf");
    let doc_id = client
        .upload_document(file_path, "application/pdf")
        .await?;
    println!("Created document with ID: {}", doc_id);
    Ok(())
}

```

As implemented in [`crates/document_storage_service/src/client.rs`](https://github.com/macro-inc/macro/blob/main/crates/document_storage_service/src/client.rs), the client abstracts S3 upload logic and returns a stable document identifier.

### Running a Full-Text Search with the OpenSearch Query Builder

This example shows how to construct a phrase query and execute it against the OpenSearch cluster:

```rust
use opensearch_client::client::OpenSearchClient;
use opensearch_query_builder::builder::QueryBuilder;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = OpenSearchClient::new().await?;
    let query = QueryBuilder::new()
        .match_phrase("content", "project roadmap")
        .size(20)
        .build();

    let results = client.search(query).await?;
    for hit in results.hits {
        println!("Found document {} – {}", hit.id, hit.source.title);
    }
    Ok(())
}

```

The builder API lives in [`crates/opensearch_query_builder/src/builder.rs`](https://github.com/macro-inc/macro/blob/main/crates/opensearch_query_builder/src/builder.rs), while the low-level client wrapper is maintained in [`crates/opensearch_client/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/opensearch_client/src/lib.rs).

### Subscribing to Real-Time Updates in the Web UI

On the frontend, the generated SDK exposes a sync client that bridges the WebSocket gateway to the React editor. This TypeScript snippet listens for CRDT updates and applies them to the local editor state:

```ts
import { createSyncClient } from "@macro/sdk";

const sync = createSyncClient({
  token: process.env.MACRO_TOKEN!,
  documentId: "doc_12345",
});

sync.on("update", (update) => {
  // Apply CRDT update to the editor
  editor.applyUpdate(update);
});

sync.connect();

```

This pattern is used in [`apps/web/src/lib/service-clients/service-sync.ts`](https://github.com/macro-inc/macro/blob/main/apps/web/src/lib/service-clients/service-sync.ts) to keep multiple users synchronized in real time.

## Summary

- **Macro Inc.** is a venture-backed startup whose `macro` repository provides the complete backend and frontend for a real-time document collaboration platform.
- The architecture is a **Rust-centric microservice** design with dedicated crates for storage, search, communication, authentication, and CRDT editing.
- **Key services** include `document-storage-service`, `search_service`, `connection_gateway`, and `packages/collaboration` (Loro-mirror).
- **Data stores** are PostgreSQL, OpenSearch, Amazon S3, and Redis.
- **Local development** is managed through `just` commands and Docker Compose, with the UI served at `http://localhost:8090/app/`.

## Frequently Asked Questions

### What is Macro Inc and what does the macro repository do?

Macro Inc. is a venture-backed startup building a cloud-native collaboration platform, and its open-source `macro` repository is the core engine that powers this ecosystem. The repository contains a Rust-based microservice architecture that handles document storage, real-time editing, full-text search, authentication, and messaging, along with a React and Tauri frontend.

### What technology stack does the macro repository use?

The backend is written primarily in **Rust** and organized as a Cargo workspace declared in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml). Services run inside **Docker** containers defined in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) and can be packaged as **AWS Lambda** functions. The build system uses **Nix** and the `just` task runner. The frontend uses **React** and **Tauri**.

### How do I run the macro repository locally?

Clone the repository, ensure Nix and `just` are installed, then run `just setup_macrodb` and `just setup_test_envs` to prepare your environment. After that, `just stack up` launches the full local stack in Docker, and the web application is available at `http://localhost:8090/app/`. Detailed instructions are in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md).

### What databases and storage does Macro Inc's platform rely on?

The platform uses **PostgreSQL** (via `macro_db_client`) for relational data such as users, projects, and messages. **OpenSearch** handles full-text search indexing, while **Amazon S3** stores raw document blobs. A **Redis** layer caches session data and real-time ephemeral state.