carbon

## Contents - [Why Carbon](#why-carbon) - [Features](#features) - [Architecture](#architecture) - [Tech Stack](#tech-stack) - [Monorepo](#monorepo) - [Getting Started](#getting-started) - [Local Dev CLI (`crbn`)](#local-dev-cli-crbn) - [Environment Variables](#environment-variables) - [Logging In](#logging-in) - [Commands](#commands) - [API](#api) - [Migration Notes](#migration-notes)
## Why Carbon We built Carbon after years of building end-to-end manufacturing systems with off-the-shelf solutions. We realized that: - Modern, API-first tooling didn't exist - Vendor lock-in bordered on extortion - There is no "perfect ERP" because each company is unique We built Carbon to solve these problems ☝️
## Features | | | | ------------------ | --------------------------------------------------- | | **ERP** | Sales, purchasing, inventory, items, accounting | | **MES** | Shop floor execution and job operations | | **QMS** | Inspections, non-conformances, CAPAs | | **MRP** | Material requirements planning | | **Traceability** | Full lot and serial tracking | | **Nested BoM** | Multi-level bills of material | | **Configurator** | Product configuration | | **Capacity Planning** | Scheduling against real resource capacity | | **Custom Fields** | Extend any record | | **API & Webhooks** | Build your own apps on top of Carbon | | **MCP Client/Server** | AI-native integration surface | | **Accounting** | GL, journals, and third-party sync | See the [full roadmap](https://github.com/orgs/crbnos/projects/1/views/1) for what's next (up next: Simulation). **Technical highlights** - Unified auth and permissions across apps - Full-stack type safety (Database → UI) - Realtime database subscriptions - Attribute-based access control (ABAC) - Role-based access control (Customer, Supplier, Employee) - Row-level security (RLS) - Composable user groups - Dependency graph for operations - Third-party integrations
## Architecture Carbon is designed to make it easy for you to extend the platform by building your own apps through our API. We provide some examples to get you started in the [examples](https://github.com/crbnos/carbon/blob/main/examples) folder.
## Tech Stack | Layer | Technology | | ---------- | --------------------------------------------------------------------- | | Framework | [React Router](https://reactrouter.com) | | Language | [TypeScript](https://www.typescriptlang.org/) | | Styling | [Tailwind](https://tailwindcss.com) | | Behavior | [Radix UI](https://radix-ui.com) | | Database | [Supabase](https://supabase.com) (Postgres + RLS) | | Auth | [Supabase](https://supabase.com) | | Cache | [Redis](https://redis.io) | | Jobs | [Inngest](https://inngest.com) | | Email | SMTP ([Nodemailer](https://nodemailer.com)) | | i18n | [Lingui](https://lingui.dev) | | Hosting | [Vercel](https://vercel.com) | | Billing | [Stripe](https://stripe.com) | | Geometry | [Rust](https://www.rust-lang.org) (FCL collision + OpenCASCADE CAD) |
## Monorepo The monorepo follows the Turborepo convention of grouping packages into two folders: ``` carbon ├── apps # applications └── packages # shared code ``` ### `/apps` | App | Description | How to run | | ----------- | -------------------------------------------------------------- | --------------------------------------------------- | | `erp` | ERP application | `pnpm dev` (boots stack + ERP via `crbn up` picker) | | `mes` | MES — shop floor | `pnpm dev` (select MES in picker, or both) | | `academy` | Training | `pnpm dev:academy` | | `starter` | Example app built on the API | `pnpm dev:starter` | | `assembler` | Geometry service (Rust): STEP → GLB + assembly motion planning | spawned by `crbn up` (needs a release binary — see [Optional: assembler](#optional-the-assembler-geometry-service)) | `pnpm dev` runs the per-worktree dev CLI (`crbn up`). ERP and MES are first-class — the CLI boots the docker stack, applies migrations, regenerates types/swagger, and spawns the selected apps behind portless. The `assembler` geometry service is spawned too when its release binary is present. Academy and starter are standalone Turborepo entries. ### `/packages` | Package | Description | | ------------------- | --------------------------------------------------------------------------- | | `@carbon/database` | Database schema, migrations and types | | `@carbon/documents` | Transactional PDFs and email templates | | `@carbon/ee` | Integration definitions and configurations | | `@carbon/config` | Shared configuration (vitest, tsconfig, tailwind) across apps and packages | | `@carbon/jobs` | Background jobs and workers | | `@carbon/logger` | Shared logger used across apps | | `@carbon/react` | Shared web-based UI components | | `@carbon/kv` | Redis cache client | | `@carbon/lib` | Third-party client libraries (slack, resend) | | `@carbon/stripe` | Stripe integration | | `@carbon/utils` | Shared utility functions used across apps and packages |
## Getting Started ### Prerequisites - [Docker](https://docs.docker.com/desktop/install/mac-install/) — the monorepo uses Docker for local development - [Node.js](https://nodejs.org) v22 (via `nvm`) - [pnpm](https://pnpm.io) (via Corepack — see below; never `npm`) You'll also want accounts with the following external services: | Service | Purpose | | ---------------------------------------------------- | -------------------------- | | [Posthog](https://us.posthog.com/signup) | Product analytics platform | | [Stripe](https://dashboard.stripe.com/login) | Payments service | | An SMTP provider (e.g. [Resend](https://resend.com)) | Email service | Posthog has a free tier which should be plenty to support local development. If you're self hosting and you don't want to use Posthog, it's pretty easy to remove the analytics. ### Clone Clone the repo into a public GitHub repository (or fork https://github.com/crbnos/carbon/fork). If you want to make the repo private, you should [acquire a commercial license](https://carbon.ms/sales) to comply with the AGPL license. ```bash git clone https://github.com/crbnos/carbon.git cd carbon ``` ### Install This repo uses **pnpm** as its package manager. Enable Corepack so the correct pnpm version (pinned via `packageManager` in `package.json`) is used automatically: ```bash corepack enable # one-time: activates pnpm shim from packageManager field nvm use # use node v22 pnpm install # install dependencies ``` The dev stack (Postgres, GoTrue, Kong, Storage, Inngest, Inbucket, Studio, Realtime) is booted later by `crbn up` — see [Local Dev CLI](#local-dev-cli-crbn) below. There is no separate "start the database" step.

Optional: the assembler geometry service

`assembler` is a Rust service (STEP → GLB + assembly motion planning) over C++ FCL and OpenCASCADE. ERP/MES run fine without it — set it up only if you need the 3D `/convert` and `/plan` endpoints. 1. **Toolchain + native build deps** (macOS): ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Rust, if not already installed brew install fcl cmake ninja draco # collision libs (+ libccd/eigen/octomap), build tools, Draco mesh compression ``` On Linux, install the equivalents from your package manager: `libfcl-dev libccd-dev libeigen3-dev liboctomap-dev libdraco-dev cmake ninja-build` plus a C/C++ toolchain. `./setup.sh` already installs Draco on macOS. If yours lives outside the Homebrew keg (`/opt/homebrew/opt/draco` on arm64), point `draco-bridge`'s build at it with `DRACO_PREFIX=/path/to/draco cargo build`. 2. **Build OCCT once** — a patched static OpenCASCADE, cached in `~/.cache/carbon-occt`. Slow (~15–30 min) but one-time per machine; re-running is a no-op once cached: ```bash ./apps/assembler/scripts/build-occt.sh ``` 3. **Build the service** — seconds once OCCT is cached (`build.rs` finds it automatically): ```bash cargo build --release -p assembler ``` `crbn up` spawns the binary when it's present. Verify it's up with `curl -sf "$ASSEMBLER_SERVICE_URL/health"` (the URL is in your worktree's `.env.local`) or by watching the `asm |` lines in the `crbn up` output. Without the binary the rest of the stack still runs — only `/convert` and `/plan` are unavailable.
## Local Dev CLI (`crbn`) `crbn` is a small CLI at `packages/dev/bin/crbn` that wraps two things: - **Git worktrees** — every feature branch can live in its own checkout dir, so you can switch branches without stashing. - **Per-worktree docker compose stack** — each worktree gets its own Postgres / Supabase services on dynamic ports, isolated under a `carbon-` compose project. Routing is handled by [portless](https://github.com/portless-dev/portless) (a local HTTPS reverse proxy that serves `*.dev` hostnames on `:443` with locally-trusted certs — installed automatically on first `crbn up`). > **Windows users:** the dev CLI (`crbn`, `setup.sh`) is POSIX-only and expects **WSL or Git Bash**. Native cmd.exe / PowerShell shells are not supported. From a WSL/Git Bash prompt, the standard flow (`./setup.sh`, `pnpm dev`, `crbn checkout …`) works the same as on macOS/Linux. Run `setup.sh` once to put `crbn` on your `$PATH` and install the `crbn` shell function (so `crbn checkout` can change cwd): ```bash ./setup.sh # writes a sentinel block to ~/.zshrc or ~/.bashrc source ~/.zshrc # or open a new shell crbn # shows commands ``` Common flows: ``` … ``` `crbn up` flags: - `--no-migrate` — skip `supabase migration up` (use when schema is already current and you just want to re-boot containers fast) - `--no-regen` — skip regenerating `packages/database/src/types.ts` + `swagger-docs-schema.ts` (auto-skipped when `--no-migrate` is set, since no schema change implies no type drift) Files synced by `crbn copy` are listed under `package.json#crbn.copy` (defaults to `[".env"]`). To uninstall the rc b