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

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:

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, a typical service exposes its API using the Axum web framework:

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

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 – Declares the Rust workspace and enumerates every crate in the crates/ directory
• 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 – 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 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 file used to orchestrate the full stack locally.

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