Documentation in the macro-inc/macro Repository: A Complete Guide to Local Docs

The macro-inc/macro repository maintains comprehensive, version-controlled documentation covering product overviews, developer onboarding, service-specific APIs, style guides, and infrastructure specifications—all stored alongside the source code.

The macro-inc/macro codebase uses a documentation-first approach where every commit includes aligned reference materials. All documentation lives within the repository structure, ensuring that developers always access guides matching the exact code version they are working with, from high-level architecture overviews in README.md to granular implementation details in individual crate directories.

Top-Level Project Documentation

The repository root contains the primary entry points for understanding Macro as a product and community.

README.md serves as the main landing page, providing a concise product description, feature matrix, architecture block diagrams, and quick-start pointers. This file explains the hexagonal service layout and directs newcomers to deeper resources.

CONTRIBUTING.md establishes the contribution workflow, detailing the PR process, required testing procedures, and CI expectations. This document is essential for developers preparing to submit changes to the codebase.

Developer Setup and Workflow Guides

The docs/ directory contains specialized guides for development environments and coding standards.

docs/RUNNING_LOCALLY.md provides step-by-step instructions to launch the full stack locally using Docker Compose and just commands. This guide covers environment setup, dependency installation, and debugging configurations necessary for feature development.

docs/STYLE_GUIDE.md functions as the definitive reference for linting and formatting rules, including specific rule identifiers such as CS-xx for Rust backend code and FE-xx for TypeScript/SolidJS frontend code. This guide ensures consistency across the Axum handlers and React components.

docs/CLOUD_STORAGE.md documents the custom S3-compatible storage layer, caching strategies, and integration points used by services like document-storage-service.

docs/PROPERTY_TARGET_ENTITY_TYPE_PLAN.md contains design notes for upcoming schema changes, providing context for the "target entity type" feature implementation.

Component-Level Documentation

The repository structures documentation hierarchically, with each deployable unit and library maintaining its own reference materials.

Service-Specific READMEs

Every microservice under services/ includes a dedicated README.md documenting its purpose, API surface, environment variables, and local testing instructions. For example, services/document_storage_service/README.md details the document storage API, while services/email_service/README.md outlines the email dispatch interface and required configuration.

Package Documentation

Shared TypeScript libraries under packages/ ship with individual README.md files detailing public APIs and usage examples. The packages/sdk/README.md serves as the primary reference for the Macro SDK, while specialized packages like loro-mirror, lexical-core, and collaboration include build steps and integration patterns.

Crate Documentation

Rust crates under crates/ maintain README.md files describing domain models, database schemas, and public function exposures. Files such as crates/email_db_client/README.md and crates/teams/README.md provide implementation context for backend database interactions and team management logic.

Infrastructure and Tooling Documentation

Beyond application code, the repository includes extensive infrastructure specifications.

infra/README.md and stack-specific files like infra/stacks/web-app/README.md outline Pulumi stack definitions, required cloud resources, and deployment pipeline configurations. These documents enable DevOps engineers to understand the AWS infrastructure managed through the Infrastructure as Code (IaC) layer.

AGENTS.md and CLAUDE.md explain internal AI-agent conventions, CLI helpers, and tooling scripts used for automated tasks. Additional tooling documentation resides in subdirectories like tooling/ and application-specific locations such as apps/web/AGENTS.md.

LICENSE.txt contains the AGPL-v3 license governing the entire codebase, while security disclosure processes are documented within README.md and CONTRIBUTING.md sections.

Referencing Documentation in Source Code

Developers can embed version-specific documentation links directly within source files to maintain context.

Linking to API Specifications in Rust

When implementing handlers, reference the service documentation and style guide using full GitHub URLs:

/// Handles creating a new `Task`.
///
/// For the expected JSON payload format, see the API spec in
/// https://github.com/macro-inc/macro/blob/main/services/document_storage_service/README.md#tasks-api
///
/// For style guidelines, see
/// https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md#cs-30-api-axum-handlers-take-shared-services-via-state
pub async fn create_task() -> Result<()> {
    // Implementation details...
    Ok(())
}

Referencing SDK Documentation

When working with TypeScript packages, link to the SDK reference:

## Using the Macro SDK

The SDK lives in `packages/sdk`. For the full API reference, see:

https://github.com/macro-inc/macro/blob/main/packages/sdk/README.md

Programmatically Constructing Documentation Paths

For tooling scripts that need to locate documentation dynamically:

fn main() {
    // Path to the Email Service documentation.
    let email_readme = concat!(
        "https://github.com/macro-inc/macro/blob/main/",
        "services/email_service/README.md"
    );
    println!("Documentation for the Email Service is at: {}", email_readme);
}

Summary

• Repository structure: All documentation resides within the macro-inc/macro repository, ensuring version alignment with source code.
• Top-level guides: README.md provides product overview while CONTRIBUTING.md defines submission workflows.
• Developer resources: docs/RUNNING_LOCALLY.md enables local setup, and docs/STYLE_GUIDE.md enforces CS-xx/FE-xx coding standards.
• Component docs: Individual README.md files exist for every service in services/, package in packages/, and crate in crates/.
• Infrastructure specs: Pulumi stacks and deployment logic are documented under infra/ directories.
• Legal and tooling: LICENSE.txt (AGPL-v3), AGENTS.md, and CLAUDE.md cover licensing and internal tooling conventions.

Frequently Asked Questions

Where is the local development setup guide located?

The local development setup guide is located at docs/RUNNING_LOCALLY.md in the repository root. This file contains step-by-step instructions for launching the full stack using Docker Compose and just commands, including environment variable configuration and debugging setup.

How do I find style guidelines for Rust and TypeScript code?

Style guidelines are defined in docs/STYLE_GUIDE.md, which specifies CS-xx rules for Rust backend development and FE-xx rules for TypeScript/SolidJS frontend code. This document covers everything from Axum handler patterns to React component structure and is enforced through the CI pipeline.

What documentation is available for individual microservices?

Each microservice under the services/ directory contains its own README.md file documenting that service's specific API endpoints, required environment variables, database schema, and local testing procedures. For example, services/email_service/README.md details the email dispatch API and configuration requirements.

Is there infrastructure documentation for deployment?

Yes, infrastructure documentation is maintained under infra/ with stack-specific READMEs such as infra/stacks/web-app/README.md. These documents describe Pulumi stack definitions, required AWS resources, and deployment pipeline configurations necessary for managing the cloud infrastructure.

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