# What Are the Main Components and Services of the Macro Application?

> Explore the core components and services of the macro-inc/macro application. Discover its Rust microservices, crates, SDKs, and SolidJS front-end, all built with hexagonal architecture.

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

---

**The Macro application is a Rust-based microservices workspace comprising 42 deployable backend services, 167 reusable Rust crates, TypeScript SDKs, and SolidJS front-end applications organized under a hexagonal architecture.**

The `macro-inc/macro` repository implements a unified collaboration platform that integrates email, chat, documents, and AI agents into a cohesive workspace. Understanding the **main components and services of the macro-inc/macro application** reveals a domain-driven architecture where inbound adapters, core business logic, and outbound infrastructure remain strictly decoupled across the monorepo structure.

## Repository Structure Overview

The root directory partitions the codebase into discrete responsibility layers according to the repository's documented layout:

- `apps/` – SolidJS client applications for web, Tauri desktop, and mobile platforms
- `services/` – 42 deployable microservices, background workers, and Lambda handlers
- `crates/` – 167 reusable Rust libraries containing domain logic and database clients
- `packages/` – Shared TypeScript utilities including the public SDK and lexical editor core
- `infra/` – Pulumi infrastructure-as-code definitions for cloud resource provisioning
- `docker/` – Local Docker Compose orchestration for development dependencies
- `nix/` – Reproducible development shells and build input definitions
- `tooling/` – Repository scripts, code generators, and automation utilities

## Core Backend Services

Macro delivers user-facing "blocks" (Email, Chat, Docs, Tasks, Canvas, Agents) through specific microservices that follow hexagonal architecture patterns. Each service exposes HTTP APIs and communicates via SQS queues, Lambda triggers, and Redis caching.

### Email Service

The **`email_service`** stores its implementation in `services/email_service/src` and provides a multi-account unified inbox with Gmail integration. It supports keyboard-driven workflows, shared inboxes, and AI-assisted email actions. Configuration and deployment details are documented in [`services/email_service/README.md`](https://github.com/macro-inc/macro/blob/main/services/email_service/README.md).

### Real-Time Chat Gateway

The **`connection_gateway`** powers channel-based messaging and direct messages through a WebSocket implementation located in `services/connection_gateway/src`. This service handles thread management and real-time presence, acting as the primary entry point for chat clients.

### Document Storage and Collaboration

Document functionality splits between **`document_storage_service`** and **`document_text_extractor`**. The storage service manages CRDT-based collaborative editing, version control, and markdown persistence, while the extractor handles content indexing. Both services reside under `services/document_storage_service/` and `services/document_text_extractor/` respectively.

### Task Management

The **`convert_service`** implements Linear-style task creation with bidirectional linking to messages, emails, and documents. Located in `services/convert_service/src`, it enables the conversion of chat messages or emails into trackable work items.

### AI Agents and Control Plane

The **`mcp_service`** (Macro Control Plane) and **`notification_service`** provide team-level memory and AI-driven automation. The MCP service manages agent orchestration and external integrations like GitHub, while the notification service handles push delivery. These implement the hexagonal pattern through `services/mcp_service/src` and `services/notification_service/src`.

### Search Infrastructure

The **`search_service`** provides full-text indexing via OpenSearch for documents, emails, and attachments. Its query handlers and indexing pipelines are defined in `services/search_service/src`.

### Authentication and Security

The **`authentication_service`** manages user login, token validation, and FusionAuth integration. Implementation details in `services/authentication_service/src` demonstrate how the service validates credentials before issuing JWTs to other microservices.

### Supporting Services

Additional specialized services include:
- **`call_recording_preview_handler`** – Records and transcribes audio calls
- **`static_file_service`** – Serves the 2-D Canvas board and embedded file links
- **`contacts_service`** – Manages CRM entities and email synchronization
- **Background workers** – `deleted_item_poller`, `sha_cleanup_worker`, and `worker_trigger` handle periodic maintenance and async pipeline triggers

## Shared Rust Crates

The `crates/` directory contains 167 domain-specific libraries that enforce compile-time safety and code reuse. Critical crates include:

- **`macro_db_client`** – Central PostgreSQL client using SQLx for compile-time query validation, located in `crates/macro_db_client/src`
- **`notification_db_client`** – Persistence layer for push notifications
- **`crm`** – Domain models for customer relationship management
- **`webhook`**, **`attachment`**, **`teams`** – Utilities for external integrations and file handling

## Front-End Applications

The `apps/` directory houses the user interface layer built with **SolidJS** and **Tauri** for cross-platform desktop deployment. TypeScript support packages reside in `packages/`:

- **`packages/sdk`** – Public TypeScript SDK for external integrations
- **`packages/collaboration`** – Real-time collaborative editing utilities
- **`packages/lexical-core`** – Rich text editor components

## Data Layer and Infrastructure

All services interact with a consistent data stack provisioned via Pulumi in `infra/stacks/web-app/`:

- **MacroDB** – PostgreSQL instance storing documents, users, projects, and communication data
- **Redis** – Caching layer and session management
- **OpenSearch** – Full-text search indexes
- **S3 / DynamoDB** – Object storage for file uploads and connection state tracking

Local development relies on [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) to orchestrate Postgres, Redis, and OpenSearch containers.

## Implementation Examples

The following snippets demonstrate how components interact within the architecture.

### Accessing the Database from a Service

Services inject the shared database client via Axum's `State` extractor. The `document_storage_service` uses `macro_db_client::MacroDbPool` to store document metadata:

```rust
use macro_db_client::MacroDbPool;
use document_storage_service::handlers::upload;

async fn upload_doc(
    pool: MacroDbPool, 
    file: Vec<u8>
) -> Result<(), anyhow::Error> {
    // Store document metadata using the shared client
    upload::store_document(&pool, file).await?;
    Ok(())
}

```

This pattern appears throughout `services/document_storage_service/src/handlers/`, where domain logic remains isolated from transport concerns.

### Calling Services via the TypeScript SDK

Client applications consume backend functionality through the SDK defined in `packages/sdk/src`:

```typescript
import { MacroClient } from '@macro/sdk';

const client = new MacroClient({ apiKey: 'YOUR_API_KEY' });
await client.email.send({
  to: ['alice@example.com'],
  subject: 'Welcome to Macro',
  body: 'Hello! Thanks for joining.',
});

```

## Summary

- **Macro** organizes 42 deployable services and 167 Rust crates into a hexagonal microservices architecture.
- Core product blocks (Email, Chat, Docs, Tasks) map to specific services like `email_service`, `connection_gateway`, and `document_storage_service`.
- The data layer consists of PostgreSQL (MacroDB), Redis, OpenSearch, and S3, accessed through shared crates like `macro_db_client`.
- Front-end applications use SolidJS and Tauri, communicating via HTTP and WebSocket protocols defined in the `connection_gateway`.

## Frequently Asked Questions

### What programming languages power the Macro application?

Macro is primarily built in **Rust** for backend services and shared libraries, with **TypeScript** used for front-end applications, SDKs, and editor components. The repository uses Nix for reproducible build environments and Pulumi (TypeScript) for infrastructure definitions.

### How do the Macro services communicate with each other?

Services communicate through **HTTP APIs**, **SQS message queues**, **Lambda triggers**, and **Redis caching**. Real-time features like chat use WebSocket connections managed by the `connection_gateway`, while asynchronous workflows rely on SQS and background workers such as `worker_trigger`.

### What database does Macro use for persistence?

Macro uses **PostgreSQL** (referred to as MacroDB) as the primary persistence layer. The `macro_db_client` crate provides SQLx-based connectivity with compile-time query checking. **OpenSearch** handles full-text search indices, while **Redis** manages caching and session state.

### Where is the front-end code located in the repository?

Front-end applications reside in the `apps/` directory, containing SolidJS implementations for web and Tauri desktop clients. Shared TypeScript utilities and the public SDK are located in `packages/sdk/src` and `packages/collaboration/`, supporting real-time collaborative features in the user interface.