# Monorepo map

> Concept: Workspace boundaries, package managers, major runtime folders, generated documentation, and where source-of-truth manifests live.

- Repository: macro-inc/macro
- GitHub: https://github.com/macro-inc/macro
- Human docs: https://grok-wiki.com/public/docs/macro-inc-macro-bb988e1a448e
- Complete Markdown: https://grok-wiki.com/public/docs/macro-inc-macro-bb988e1a448e/llms-full.txt

## Source Files

- `rust/cloud-storage/Cargo.toml`
- `rust/sync-service/Cargo.toml`
- `js/package.json`
- `js/app/package.json`
- `infra/README.md`
- `docs/docs.json`

---

---
title: "Monorepo map"
description: "Concept: Workspace boundaries, package managers, major runtime folders, generated documentation, and where source-of-truth manifests live."
---

Macro is organized as several adjacent workspaces rather than one repository-wide package workspace: Rust backend services live under `rust/cloud-storage`, the Cloudflare Durable Object sync worker lives under `rust/sync-service`, the Solid/Tauri app and JS services live under `js`, Pulumi infrastructure lives under `infra`, and the Mintlify documentation site lives under `docs`.

## Repository boundary map

```text
.
├── justfile                         # Local orchestration entrypoint
├── docker-compose*.yml              # Local service, database, and E2E topology
├── flake.nix                        # Nix shells and cached Rust/API build jobs
├── rust/
│   ├── rust-toolchain.toml          # Rust toolchain source of truth
│   ├── cloud-storage/               # Main Rust Cargo workspace
│   └── sync-service/                # Cloudflare Worker/Durable Object sync runtime
├── js/
│   ├── package.json                 # Bun workspace for app + selected JS packages
│   ├── app/                         # Solid app, package libraries, tests, Tauri frontend
│   ├── lexical-core/                # Shared Lexical package
│   ├── lexical-service/             # Wrangler service for Lexical conversion
│   ├── websocket-service/           # Standalone Bun WebSocket service
│   └── analytics-proxy/             # Standalone Wrangler proxy
├── infra/
│   ├── package.json                 # Bun workspace for Pulumi stacks/packages
│   ├── stacks/                      # Deployable Pulumi projects
│   └── packages/                    # Shared Pulumi resource libraries
└── docs/
    ├── docs.json                    # Rendered docs navigation/config
    ├── package.json                 # Mintlify scripts
    └── AI/mcp/tools/                # Generated MCP tool reference pages
```

<Info>
The repository root is orchestration-oriented. Do not infer JavaScript workspace membership from the root `package.json`; the active JS workspaces are declared in `js/package.json`, `js/app/package.json` scripts, and `infra/package.json`.
</Info>

## Package managers and workspace manifests

| Boundary | Source-of-truth manifest | Package manager/tooling | Lock/config files | Scope |
| --- | --- | --- | --- | --- |
| Rust backend services | `rust/cloud-storage/Cargo.toml` | Cargo, `just`, SQLx | `rust/cloud-storage/Cargo.lock`, `.sqlx/`, `rust/rust-toolchain.toml` | Axum services, Lambda handlers, model crates, service clients, database migrations |
| Sync worker | `rust/sync-service/Cargo.toml`, `rust/sync-service/wrangler.toml` | Cargo, Wrangler, npm for Docker install | `rust/sync-service/Cargo.lock`, `package.json`, D1 migrations | Cloudflare Worker with Durable Objects, D1, R2, KV, Bebop-generated bindings |
| JS app workspace | `js/package.json`, `js/app/package.json` | Bun `1.3.5` at `js/` | `js/bun.lock`, `js/app/bun.lock`, `js/app/biome.jsonc`, `js/app/tsconfig.json` | Solid app, package libraries, generated service clients, Playwright/Vitest tests |
| Tauri app | `js/app/tauri/Cargo.toml`, `js/app/tauri/src-tauri/tauri.conf.json` | Cargo, Tauri CLI, Bun build hooks | `js/app/tauri/Cargo.lock` | Desktop/mobile shell around `js/app/packages/app/dist` |
| Infrastructure | `infra/package.json` | Bun `1.2.0`, Pulumi, TypeScript | `infra/bun.lock`, `infra/tsconfig.json`, per-stack `Pulumi*.yaml` | AWS infrastructure stacks and shared resource packages |
| Docs | `docs/docs.json`, `docs/package.json` | Bun, Mintlify CLI | generated `docs/config/tool-pages.json` | Product docs and generated MCP tool reference |
| Nix shells/builds | `flake.nix` | Nix, Fenix, Crane | `flake.lock` | Reproducible Rust, JS app, Pulumi, SQLx, Bun, pnpm, and Tauri tools |

### Nested package-manager exceptions

- `js/loro-mirror/package.json` has pnpm scripts and pnpm overrides. It is included by the `js/package.json` workspace list, but its own scripts call `pnpm`.
- `js/websocket-service` and `js/analytics-proxy` have package manifests but are not listed in the `js/package.json` workspace array.
- `infra/stacks/web-app` has a Pulumi project, but `infra/tsconfig.json` explicitly excludes `stacks/web-app` from the infra TypeScript check.

## Major runtime folders

| Folder | Runtime role | Primary manifests |
| --- | --- | --- |
| `rust/cloud-storage` | Main Rust backend workspace for services such as authentication, document storage, document cognition, email, notifications, MCP, search, static files, image proxy, unfurling, and Lambda-style workers | `Cargo.toml`, `justfile`, `database.just`, `sqlx.just`, crate-level `Cargo.toml` files |
| `rust/cloud-storage/macro_db_client` | MacroDB client and SQL migrations | `Cargo.toml`, `migrations/*.sql`, crate `justfile` |
| `rust/cloud-storage/ai_tools` | Rust AI/MCP tool registry used by app and docs generators | `Cargo.toml`, `src/`, generated `schemas/tools.json` after running schema generation |
| `rust/sync-service` | Cloudflare Worker sync service using Durable Objects, D1, R2, KV, and Bebop bindings | `Cargo.toml`, `wrangler.toml`, `Dockerfile`, `database/user-peer-mapping/migrations`, `bebop/schema.bop` |
| `js/app/packages/app` | Solid/Vite frontend app package | `package.json`, `vite.config.ts`, `tsconfig.json` |
| `js/app/packages/service-clients` | Generated and checked-in frontend API clients | `orval.config.ts`, per-service `openapi.json`, generated client/schema folders |
| `js/app/tauri` | Tauri Rust workspace and plugins for desktop/mobile packaging | workspace `Cargo.toml`, plugin crates, `src-tauri/tauri.conf.json` |
| `js/lexical-service` | Wrangler service for Lexical document conversion | `package.json`, `wrangler` scripts |
| `infra/stacks/*` | Deployable Pulumi projects; run Pulumi from inside a stack directory | `Pulumi.yaml`, `Pulumi.dev.yaml`, `Pulumi.prod.yaml`, `index.ts` |
| `infra/packages/*` | Shared Pulumi abstractions for services, VPC, Lambda, resources, and stack constants | package `src/index.ts` exports |
| `docs` | Mintlify documentation site | `docs.json`, MDX files, generator scripts |

<Warning>
There are two Rust packages named `sync_service` in different workspaces: `rust/sync-service` is the Cloudflare Worker runtime, while `rust/cloud-storage/sync_service` is a crate inside the backend workspace. Keep workspace-relative paths explicit when changing sync code.
</Warning>

## Backend Cargo workspace

`rust/cloud-storage/Cargo.toml` owns the backend Cargo workspace membership and shared dependency versions. Most backend crates set `publish = false` and depend on sibling crates by relative `path`.

Common commands run from `rust/cloud-storage`:

```bash
just check          # SQLX_OFFLINE=true cargo check with warnings denied
just clippy         # workspace clippy with all features
just format         # cargo fmt
just prepare_db     # refresh SQLx offline cache through sqlx.just
just build          # SQLX_OFFLINE=true cargo build
```

Database lifecycle commands are routed through `rust/cloud-storage/macro_db_client/justfile`:

```bash
just macro_db_client/create_db
just macro_db_client/migrate_db
just macro_db_client/drop_db -y -f
```

MacroDB schema migrations live under `rust/cloud-storage/macro_db_client/migrations`. Several worker/test crates also carry local migrations for their own test schemas.

## Sync worker boundary

`rust/sync-service` is a separate Cargo project compiled to WebAssembly for Cloudflare Workers. Its `wrangler.toml` defines:

| Binding | Purpose |
| --- | --- |
| `DOCUMENT_SYNC_SESSION` | Durable Object class |
| `USER_PEER_MAPPING` | D1 database with migrations under `database/user-peer-mapping/migrations` |
| `DOCUMENT_SNAPSHOT_BUCKET` | R2 snapshot bucket |
| `DOCUMENT_VERSIONING_KV` | KV namespace |
| `SNAPSHOT_STORE_KV` | KV namespace |
| `INTERNAL_API_SECRET_KEY`, `SPS_URL`, `ENVIRONMENT` | Worker runtime variables per environment |

The Dockerfile installs Node 22, `worker-build`, Wrangler dependencies, builds Bebop TypeScript bindings from `bebop/schema.bop`, applies local D1 migrations, and starts Wrangler on port `8787`.

## Frontend and app packages

`js/package.json` declares the Bun workspace boundary:

```json
[
  "app",
  "app/packages/*",
  "app/infra/*",
  "loro-mirror",
  "lexical-core",
  "lexical-service"
]
```

`js/app/package.json` is the app-level command surface:

```bash
cd js/app
bun run dev          # Vite app through packages/app
bun run build        # Vite production-style build
bun run test         # Vitest
bun run local:e2e    # Playwright with LOCAL_E2E=true
bun run check        # TypeScript + Biome
bun run gen-api      # Rust OpenAPI binaries -> service-clients
bun run gen-tools    # Rust AI tool schemas -> DCS tool types
```

`js/app/tsconfig.json` includes `packages/**/*`, `../loro-mirror/**/*`, and `../lexical-core/**/*`, and defines path aliases for generated service clients such as `@service-storage/*`, `@service-cognition/*`, `@service-email/*`, and `@service-sync/*`.

### Tauri packaging

The Tauri workspace lives in `js/app/tauri`. `src-tauri/tauri.conf.json` points `frontendDist` at `../../packages/app/dist`, uses `http://localhost:3000` for development, and delegates build hooks back to the app justfile:

```json
{
  "beforeDevCommand": { "script": "just dev-tauri", "cwd": "../.." },
  "beforeBuildCommand": { "script": "just build-tauri", "cwd": "../.." }
}
```

Use `js/app/justfile` for app-local run modes:

```bash
cd js/app
just local                    # Vite against local services
just local-dcs                # Local cognition service only
just local-dss                # Local document storage service only
just build-prod               # Production-mode frontend bundle
just dist-archive             # Zip dist for native_app_server tests
```

## Infrastructure workspace

Infrastructure code is TypeScript Pulumi under `infra`. The root `infra/package.json` declares Bun workspaces for `stacks/*` and `packages/*`, requires Node `>=21`, and enforces Bun through a `preinstall` script.

Run Pulumi from inside a stack directory:

```bash
cd infra/stacks/document-storage
pulumi up --stack dev
pulumi up --stack prod
```

Operational defaults from the infra README:

| Setting | Value |
| --- | --- |
| Cloud provider | AWS |
| Main AWS region | `us-east-1` |
| Logging provider | Datadog |
| Datadog region | `us-central-1` |

Shared stack constants and exported helpers live in `infra/packages/shared/src/index.ts`; reusable resource constructors live in `infra/packages/resources/src/index.ts`.

## Local orchestration

The root `justfile` is the local runtime entrypoint. It freezes Docker Compose resources under the `macro` project name so multiple checkouts share the same local containers, networks, and volumes.

Primary commands:

```bash
just setup          # Environment, networks, LocalStack, DBs, FusionAuth, Rust images
just run_dbs -d     # Postgres + Redis
just run_local      # Docker Compose services
just run_local --build
just stop-local
just local-e2e
just local-e2e-rust
just local-e2e-all
```

Local service topology is defined by:

| File | Role |
| --- | --- |
| `docker-compose.yml` | Rust services, sync worker, lexical service, WebSocket service, FusionAuth include, service networks |
| `docker-compose-databases.yml` | Postgres/pgvector, Redis Stack, OpenSearch, external volumes |
| `docker-compose.local-e2e.yml` | Local-only overrides for deterministic E2E data and LocalStack resources |
| `local_stack.just` | LocalStack setup recipes imported by the root justfile |

The local E2E harness seeds deterministic data through `rust/cloud-storage/seed_cli` and runs Playwright from `js/app`.

## Generated code and documentation

| Generated surface | Command | Source of truth | Output |
| --- | --- | --- | --- |
| OpenAPI JSON and frontend clients | `cd js/app && bun scripts/generate-api-schema.ts` | Rust service OpenAPI binaries built from `rust/cloud-storage` | `js/app/packages/service-clients/service-*/openapi.json` and `generated/` folders |
| OpenAPI freshness check | `cd js/app && bun scripts/generate-api-schema.ts --check` | Same as above | Fails if generated files differ from Git |
| DCS tool TypeScript/Zod types | `cd js/app && bun run gen-tools` | `rust/cloud-storage/ai_tools` and `gen_tool_schemas` | `js/app/packages/service-clients/service-cognition/generated/tools` |
| MCP docs pages | `cd docs && bun run generate:tools` | Rust AI tool schemas from `rust/cloud-storage/ai_tools` | `docs/AI/mcp/tools/*.mdx`, `docs/config/tool-pages.json` |
| Docs navigation | edit `docs/docs.json` | Mintlify config | Rendered docs tabs/groups/pages |

<Note>
AI tool references are generated from local Rust schema code and checked-in files. The generation path does not require a specific model provider or hosted AI connector.
</Note>

## Source-of-truth checklist

When changing a boundary, update the owning manifest first:

| Change | Update first | Then verify |
| --- | --- | --- |
| Add a Rust backend crate | `rust/cloud-storage/Cargo.toml` | `cd rust/cloud-storage && just check` |
| Add a Rust service OpenAPI client | Rust service `*_openapi` binary and `js/app/scripts/services.ts` | `cd js/app && bun scripts/generate-api-schema.ts --check` |
| Add a database migration | `rust/cloud-storage/macro_db_client/migrations` | `just rust/cloud-storage/macro_db_client/migrate_db` or local setup recipe |
| Add a frontend package | `js/app/packages/<name>/package.json` | `cd js/app && bun run check` |
| Add a Tauri plugin | `js/app/tauri/Cargo.toml` workspace members | Tauri dev/build command |
| Add a Pulumi stack | `infra/stacks/<stack>/Pulumi.yaml` and `infra/package.json` workspace match | `cd infra && bun run check` unless intentionally excluded |
| Add generated MCP docs | Rust tool registry and docs generator | `cd docs && bun run generate:tools && bun run lint` |
| Change local runtime wiring | `docker-compose*.yml` and root `justfile` | `just run_local --build` or `just local-e2e` |

## Related pages

<CardGroup>
  <Card title="Local development" href="/development">
    Commands and environment notes for running Macro locally.
  </Card>
  <Card title="MCP overview" href="/AI/mcp/overview">
    Product-facing documentation for Macro MCP surfaces.
  </Card>
  <Card title="MCP tool reference" href="/AI/mcp/tools">
    Generated tool pages derived from the Rust tool registry.
  </Card>
</CardGroup>