# Main Directories and Their Purposes in the macro-inc/macro Repository

> Explore the macro-inc/macro repository's eight main directories. Understand the purpose of apps, crates, docker, infra, packages, docs, .github, and tooling in this mono-repo.

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

---

**The macro-inc/macro repository organizes its full-stack codebase into eight primary directories—`apps/`, `crates/`, `docker/`, `infra/`, `packages/`, `docs/`, `.github/`, and `tooling/`—that separate Rust backend microservices, SolidJS frontend applications, infrastructure-as-code, and shared SDKs into a cohesive mono-repo structure.**

The macro-inc/macro project is a mono-repo housing a complete workspace built with **Rust** for backend services and **SolidJS/TypeScript** for the frontend. Understanding the main directories and their purposes in macro-inc/macro is essential for navigating its architecture, which splits functionality into discrete, maintainable chunks across backend microservices, client applications, and deployment tooling.

## apps/ – Frontend Applications

The `apps/` directory contains all client-side applications. Currently, the primary occupant is `apps/web`, which implements the user interface using **SolidJS**, **Vite**, and **TypeScript**. This directory isolates the frontend build pipeline from the backend Rust workspace.

To run the web UI locally, navigate to the repository root and execute the standard Node.js workflow:

```bash
npm install        # Installs dependencies including the TypeScript SDK from packages/sdk

npm run dev        # Starts the Vite development server using apps/web/vite.config.ts

```

## crates/ – Rust Backend Workspace

The `crates/` directory serves as the **Rust workspace root** for all backend microservices. Each subdirectory represents a separate, independently compilable crate that implements a specific domain of the Macro platform.

Key services include:

- **`document-storage-service`** – Handles persistence of user documents
- **`email_service`** – Manages transactional email delivery
- **`authentication_service`** – Implements auth flows and session management

According to the source code in [`crates/email_service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/email_service/src/lib.rs), a typical service exposes its API using the Axum web framework:

```rust
// crates/email_service/src/lib.rs
use axum::{routing::post, Router};

/// Sets up the Email API routes.
pub fn router() -> Router {
    Router::new()
        .route("/send", post(handlers::send_email))
}

```

The workspace configuration in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) lists every crate under this directory and defines shared dependencies across the backend.

## docker/ – Container Orchestration

The `docker/` directory houses **Dockerfiles** and **Compose** configurations used to build, run, and test services locally or in CI. It includes service-specific container definitions such as `websocket-service.Dockerfile` and `lexical-service.Dockerfile`.

The [`docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker-compose.yml) file orchestrates the entire stack for integration testing, ensuring that the Rust microservices and any supporting infrastructure can spin up together with a single command.

## infra/ – Infrastructure as Code

The `infra/` directory contains **Pulumi** scripts and **Turbo** repository configurations that provision cloud resources for production deployments. This infrastructure-as-code approach allows the team to define networking, compute, and storage resources using TypeScript.

For example, the web application preview stack is configured in `infra/stacks/web-app-preview/`:

```typescript
import * as pulumi from "@pulumi/pulumi";

const stack = new pulumi.StackReference("macro/web-app-preview");
export const url = stack.getOutput("url");

```

## packages/ – Developer SDKs

The `packages/` directory distributes language-specific **SDKs** that expose Macro’s APIs to external developers. The flagship example is `packages/sdk`, which provides the **TypeScript SDK** consumed by the frontend application and third-party integrators.

This separation ensures that API client code is versioned independently from the services that implement the backend logic.

## docs/ – Project Documentation

The `docs/` directory stores human-readable guides, architecture decision records, and style conventions. It contains explanations of the development workflow, contribution guidelines, and high-level system overviews that complement the inline code documentation.

## .github/ – CI/CD and Automation

The `.github/` directory defines **GitHub Actions** workflows, issue templates, and repository governance files like `CODEOWNERS`. These pipelines automatically lint, test, and publish each microservice when code is merged to the main branch, ensuring consistent quality across the mono-repo.

## tooling/ – Build Utilities and Scripts

The `tooling/` directory (containing subdirectories like `xtask`) holds helper binaries and automation scripts used for repository-wide tasks. These tools handle code generation, custom linting steps, and complex build orchestration that falls outside the scope of standard cargo or npm commands.

## Root Configuration Files

Several critical files sit at the repository root to tie the workspace together:

- **[`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml)** – Declares the Rust workspace and enumerates every crate in the `crates/` directory
- **[`package.json`](https://github.com/macro-inc/macro/blob/main/package.json)** – Top-level Node manifest that defines npm scripts and workspace dependencies for the frontend
- **`justfile`** – Task runner configuration used by developers to execute common commands like `just build`, `just test`, and `just deploy`
- **[`README.md`](https://github.com/macro-inc/macro/blob/main/README.md)** – Central onboarding document explaining Macro’s purpose and development setup

## Summary

- **`apps/`** – Contains the SolidJS/Vite frontend application (`apps/web`).
- **`crates/`** – Houses the Rust workspace with independent microservice crates for document storage, email, authentication, and more.
- **`docker/`** – Provides Dockerfiles and Compose files for local development and testing.
- **`infra/`** – Stores Pulumi infrastructure-as-code for cloud resource provisioning.
- **`packages/`** – Distributes language-specific SDKs including the TypeScript client library.
- **`docs/`** – Holds architectural documentation and development guides.
- **`.github/`** – Configures CI/CD pipelines and repository automation.
- **`tooling/`** – Contains build scripts and helper utilities for repository maintenance.

## Frequently Asked Questions

### What is the purpose of the crates/ directory in macro-inc/macro?

The `crates/` directory functions as the Rust workspace root that organizes all backend microservices into separate, compilable units. Each crate—such as `email_service` or `document-storage-service`—implements a discrete domain of the Macro platform and is listed in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) workspace manifest.

### How does the apps/ directory differ from packages/ in macro-inc/macro?

The `apps/` directory contains deployable end-user applications like the SolidJS web interface, while the `packages/` directory houses reusable libraries and SDKs meant for distribution to other developers. For example, `apps/web` consumes the TypeScript SDK located in `packages/sdk`, separating the frontend implementation from the API client code.

### What infrastructure tools does macro-inc/macro use for deployment?

The repository uses **Pulumi** for infrastructure-as-code, with TypeScript-based configuration files located in the `infra/` directory. These scripts provision cloud resources for production and preview environments, working alongside **Docker** configurations stored in `docker/` for containerized service deployment.

### Where are the Docker configurations located in the macro-inc/macro repository?

All Docker-related assets reside in the `docker/` directory at the repository root. This includes service-specific Dockerfiles (such as `websocket-service.Dockerfile` and `lexical-service.Dockerfile`) and the [`docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker-compose.yml) file used to orchestrate the full stack locally.