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

> Explore the comprehensive documentation within the macro-inc/macro repository. Find guides on product overviews, developer onboarding, APIs, style guides, and infrastructure specs.

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

---

**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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/README.md) documenting its purpose, API surface, environment variables, and local testing instructions. For example, [`services/document_storage_service/README.md`](https://github.com/macro-inc/macro/blob/main/services/document_storage_service/README.md) details the document storage API, while [`services/email_service/README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/README.md) files detailing public APIs and usage examples. The [`packages/sdk/README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/README.md) files describing domain models, database schemas, and public function exposures. Files such as [`crates/email_db_client/README.md`](https://github.com/macro-inc/macro/blob/main/crates/email_db_client/README.md) and [`crates/teams/README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/infra/README.md)** and stack-specific files like [`infra/stacks/web-app/README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/AGENTS.md)** and **[`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/apps/web/AGENTS.md).

**[`LICENSE.txt`](https://github.com/macro-inc/macro/blob/main/LICENSE.txt)** contains the AGPL-v3 license governing the entire codebase, while security disclosure processes are documented within [`README.md`](https://github.com/macro-inc/macro/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/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:

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

```markdown

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

```rust
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`](https://github.com/macro-inc/macro/blob/main/README.md) provides product overview while [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) defines submission workflows.
- **Developer resources:** [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) enables local setup, and [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) enforces CS-xx/FE-xx coding standards.
- **Component docs:** Individual [`README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/LICENSE.txt) (AGPL-v3), [`AGENTS.md`](https://github.com/macro-inc/macro/blob/main/AGENTS.md), and [`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.