# Overview

> Overview: Public entry points, repository surfaces, runtime assumptions, and the shortest successful path through the docs.

- 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

- `README.md`
- `RUNNING_LOCALLY.md`
- `js/app/README.md`
- `rust/cloud-storage/AGENTS.md`
- `docker-compose.yml`
- `docs/docs.json`

---

---
title: "Overview"
description: "Overview: Public entry points, repository surfaces, runtime assumptions, and the shortest successful path through the docs."
---

Macro is a SolidJS and Rust monorepo for the Macro workspace: a static SPA frontend, Rust backend services, generated MCP tool documentation, Pulumi infrastructure, Docker Compose local services, and deterministic local smoke-test fixtures.

## Public entry points

| Surface | Entry point | Backing repository area |
| --- | --- | --- |
| Web application | `https://macro.com/app` | `js/app`, `infra/stacks/web-app` |
| Product docs | `docs.macro.com` site config | `docs/docs.json`, `docs/index.mdx`, `docs/product/*` |
| MCP server | `https://mcp-server.macro.com/mcp` | `rust/cloud-storage/mcp_service`, `rust/cloud-storage/ai_tools`, `docs/AI/mcp/*` |
| Local backend stack | `just run_local` | `justfile`, `docker-compose.yml`, `docker-compose-databases.yml` |
| Local E2E smoke stack | `just local-e2e` | `docker-compose.local-e2e.yml`, `rust/cloud-storage/seed_cli`, `js/app/tests/e2e` |

<Note>
The local setup is explicitly single-instance. The root `justfile` exports `COMPOSE_PROJECT_NAME=macro`, and the Compose files use the fixed project name `macro`, so multiple checkouts share the same local containers, volumes, networks, LocalStack, and FusionAuth resources.
</Note>

## Repository surfaces

:::files
```text
.
├── README.md                         # product, security, license, community
├── RUNNING_LOCALLY.md                # supported local setup and E2E path
├── justfile                          # root setup, local stack, E2E orchestration
├── docker-compose*.yml               # local services, databases, E2E overrides
├── local_stack.just                  # LocalStack SQS, DynamoDB, and S3 setup
├── docs/                             # public docs site and generated MCP docs
├── js/
│   ├── app/                          # SolidJS/Vite frontend workspace
│   ├── lexical-service/              # Lexical conversion service
│   └── websocket-service/            # Bun websocket service
├── rust/
│   ├── cloud-storage/                # Rust service workspace
│   └── sync-service/                 # sync service container
├── infra/                            # Pulumi stacks and shared service package
└── agents/transcription/             # transcription agent service
```
:::

### Frontend

The frontend lives in `js/app` and uses Bun, Vite, SolidJS, Tailwind, TypeScript, and workspace packages under `js/app/packages/*`. The app package builds a static SPA with base path `/app`; development serves from `/` on port `3000` by default.

Common commands:

```bash
cd js/app
bun i
just local
bun run check
bun run local:e2e
```

The Vite config exposes build-time values such as `import.meta.env.__APP_VERSION__`, `ASSETS_PATH`, `__LOCAL_DOCKER__`, `__LOCAL_JWT__`, and `__GIT_BRANCH__`.

### Rust services

The main backend surface is the Cargo workspace in `rust/cloud-storage`. It contains service binaries, worker binaries, Lambda handlers, database clients, domain crates, generated schemas, and integration tests.

Representative service binaries include:

| Binary | Local Compose service | Port mapping |
| --- | --- | --- |
| `authentication_service` | `authentication-service` | `8080:8080` |
| `connection_gateway_service` | `connection_gateway` | `8082:8080` |
| `contacts_service` | `contacts_service` | `8083:8080` |
| `document_storage_service` | `document_storage_service` | `8086:8080` |
| `email_service` | `email_service` | `8087:8080` |
| `notification_service` | `notification_service` | `8089:8080` |
| `search_processing_service` | `search_processing_service` | `8092:8080` |
| `static_file_service` | `static_file_service` | `8094:8080` |
| `unfurl_service` | `unfurl_service` | `8095:8080` |
| `image_proxy_service` | `image_proxy_service` | `8097:8080` |

`rust/cloud-storage/Dockerfile.dev` builds the standard service bundle into the `macro-local-rust-services:dev` image. `search_processing_service` uses a separate Dockerfile and is behind the `processors` Compose profile.

### Docs and MCP reference

The docs site is configured by `docs/docs.json`. Current navigation contains:

- Getting Started: `docs/index.mdx`
- Product pages: AI Chat, Email, Channels, Docs, Canvas, Tasks, Search, Files
- MCP setup: `docs/AI/mcp/overview.mdx`
- Generated MCP tool pages: `docs/AI/mcp/tools/*`
- Changelog: `docs/changelog/introduction`

MCP tool pages are generated from the Rust tool registry:

```bash
cd docs
bun install
bun run generate:tools
bun run dev
```

The generator builds `gen_tool_schemas` from `rust/cloud-storage`, reads `rust/cloud-storage/ai_tools/schemas/tools.json`, writes MDX pages under `docs/AI/mcp/tools`, and updates `docs/config/tool-pages.json`.

<Info>
The MCP docs and transport are portable at the repository boundary: the public setup page points clients at the hosted HTTP MCP endpoint and authenticates through Macro OAuth. Tool references are generated from repository schemas rather than from a specific client, editor, or model provider.
</Info>

### Infrastructure

Infrastructure lives under `infra/stacks/*` and shared Pulumi packages under `infra/packages/*`.

Important stacks include:

| Stack area | Purpose |
| --- | --- |
| `infra/stacks/web-app` | Publishes the built SPA to S3 and wires route/encoding Lambda functions |
| `infra/stacks/document-storage` | Creates document storage buckets, replication, and the shared ECS cluster |
| `infra/stacks/mcp-server` | Deploys the MCP service and configures OAuth, Redis, queues, buckets, and secrets |
| `infra/stacks/fusionauth-instance` | Local and deployed FusionAuth configuration |
| `infra/packages/service` | Shared ECS Fargate service component with load balancer, IAM role, Datadog sidecars, and environment variables |

## Runtime assumptions

### Required local tools

`RUNNING_LOCALLY.md` lists these local prerequisites:

- `sops`
- Docker
- AWS CLI/configuration
- SQLx / `sqlx-cli`
- Pulumi
- Bun
- Node
- `just`

If Nix is available, the repo supports `nix develop` for toolchain management.

### Local data plane

The default local stack uses:

| Dependency | Local implementation |
| --- | --- |
| PostgreSQL | `pgvector/pgvector:pg16` on `localhost:5432` |
| Redis | `redis/redis-stack` on `localhost:6379` and UI/tools on `8001` |
| OpenSearch | `opensearchproject/opensearch` on `9200` |
| AWS SQS/DynamoDB/S3 | LocalStack v4 on `4566` |
| FusionAuth | `infra/stacks/fusionauth-instance/docker-compose.yml` |
| Static CDN emulation | nginx `static_file_cdn` on `8100` |

Local E2E overrides force services onto local Postgres, Redis, LocalStack queues, LocalStack buckets, and deterministic seed data.

### Environment and secrets

The root setup path decrypts `.env-local*.enc` into `.env` with `sops`, patches local FusionAuth values when available, creates shared Docker networks and volumes, initializes local AWS resources, initializes databases, and builds the Rust dev service image.

```bash
just setup
```

Use `just get_environment` when only the `.env` file is needed.

## Shortest successful path

<Steps>
<Step title="Read the product and license boundary">

Start with `README.md` for the public product surface, security contact, AGPLv3 license, and self-hosting note.

</Step>

<Step title="Initialize the local environment">

Run the repository setup from the root:

```bash
just setup
```

This prepares `.env`, Docker networks and volumes, LocalStack resources, local databases, FusionAuth, and Rust service images.

</Step>

<Step title="Run backend services">

```bash
just run_local
```

If service images changed, rebuild during startup:

```bash
just run_local --build
```

Add the `processors` profile only when you need processor services such as `search_processing_service`.

</Step>

<Step title="Run the frontend">

```bash
cd js/app
bun i
just local
```

The Vite dev server defaults to port `3000`.

</Step>

<Step title="Run deterministic smoke tests">

```bash
just local-e2e
```

For Rust ignored integration tests against the same local stack:

```bash
just local-e2e-rust
```

For both Rust and Playwright smoke coverage:

```bash
just local-e2e-all
```

</Step>
</Steps>

## Verification signals

| Command | Expected signal |
| --- | --- |
| `just run_local` | Compose services start and healthchecks pass |
| `just local-e2e` | LocalStack setup completes, seed data loads, Playwright smoke tests run |
| `cd rust/cloud-storage && just check` | Rust workspace type-checks with `SQLX_OFFLINE=true` |
| `cd rust/cloud-storage && just clippy` | Workspace clippy passes with warnings denied |
| `cd js/app && bun run check` | TypeScript and Biome checks pass |
| `cd docs && bun run generate:tools` | MCP tool pages regenerate from Rust schemas |
| `cd docs && bun run lint` | Docs broken-link check runs through Mintlify |

## Failure modes to check first

| Symptom | Likely cause | Check |
| --- | --- | --- |
| Local services share unexpected state | Compose project is intentionally frozen to `macro` | Do not run two local stacks at the same time |
| `just run_local` fails before services start | Missing `.env` | Run `just get_environment` or `just setup` |
| FusionAuth values are missing | Local Pulumi/FusionAuth setup not complete | Run `just setup` or inspect `infra/stacks/fusionauth-instance` |
| Local E2E seed refuses to run | Safety guard rejected the target database | Ensure `LOCAL_E2E_SEED=true` and `DATABASE_URL` targets local `macrodb` |
| SQLx reports missing cached query data | Rust SQL changed without refreshing offline cache | Run `just prepare_db` from `rust/cloud-storage` |
| Docs tool pages drift from code | Generated pages were not rebuilt | Run `cd docs && bun run generate:tools` |

## Related pages

<CardGroup cols={2}>
  <Card title="MCP setup" href="/AI/mcp/overview">
    Connect clients to Macro's hosted MCP endpoint.
  </Card>
  <Card title="MCP tool reference" href="/AI/mcp/tools">
    Inspect generated tool schemas from the Rust registry.
  </Card>
  <Card title="Product introduction" href="/">
    Navigate the public product docs surface.
  </Card>
</CardGroup>