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

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.

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 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:

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:

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.

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