carbon

Techstack

• React Router – framework
• Typescript – language
• Tailwind – styling
• Radix UI - behavior
• Supabase - database
• Supabase – auth
• Redis - cache
• Inngest - jobs
• Resend – email
• Lingui - i18n
• Novu – notifications
• Vercel – hosting
• Stripe - billing

Codebase

The monorepo follows the Turborepo convention of grouping packages into one of two folders.

1. /apps for applications
2. /packages for shared code

/apps

| Package Name | Description | Local Command | | ------------ | --------------- | --------------------- | | erp | ERP Application | npm run dev | | mes | MES | npm run dev:mes | | academy | Academy | npm run dev:academy | | starter | Starter | npm run dev:starter |

/packages

| Package Name | 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 |

Development

Setup

1. Clone the repo into a public GitHub repository (or fork https://github.com/crbnos/carbon/fork). If want to make the repo private, you should acquire a commercial license to comply with the AGPL license.

   git clone https://github.com/crbnos/carbon.git
   

2. Go to the project folder

   cd carbon
   

Make sure that you have Docker installed on your system since this monorepo uses the Docker for local development.

In addition you must configure the following external services:

| Service | Purpose | URL | | ------- | -------------------------- | -------------------------------------------------------------- | | Posthog | Product analytics platform | https://us.posthog.com/signup | | Stripe | Payments service | https://dashboard.stripe.com/login | | Resend | Email service | https://resend.com | | Novu | Notifications service | https://dashboard.novu.co/auth/sign-in |

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.

Installation

First download and initialize the repository dependencies.

$ nvm use           # use node v20
$ npm install       # install dependencies
$ npm run db:start  # pull and run the containers

Create an .env file and copy the contents of .env.example file into it

$ cp ./.env.example ./.env

1. Social Sign In: Signing in requires you to setup one of two methods:

• Email requires a Resend API key (you'll set this up later on)
• Sign-in with Google requires a Google auth client with these variables. See the Supabase docs for instructions on how to set this up:
  • Set Authorized JavaScript origins to only http://127.0.0.1:54321
  • Set Authorized redirect URIs to http://127.0.0.1:54321/auth/v1/callback
• You should set environment variables like the following.
  • SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID="******.apps.googleusercontent.com"
  • SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_SECRET="GOCSPX-****************"

2. Supabase: Start up the backend services using npm run db:start. Find the following values in its output to set the supabase entries:

• SUPABASE_SERVICE_ROLE_KEY=[service_role key]
• SUPABASE_ANON_KEY=[anon key]

3. Redis (Caching): Set up a Redis instance (local or cloud) and add the connection URL. You can set one up in the cloud easily using Upstash:

• REDIS_URL=[redis://user:password@host:port]

4. Posthog (Analytics): In Posthog go to https://[region].posthog.com/project/[project-id]/settings/project-details to find your Project ID and Project API key:

• POSTHOG_API_HOST=[https://[region].posthog.com]
• POSTHOG_PROJECT_PUBLIC_KEY=[Project API Key starting 'phc*']

5. Stripe (Payment service) - Create a stripe account, add a STRIPE_SECRET_KEY from the Stripe Settings > Developers interface

• STRIPE_SECRET_KEY="sk_test_*************"

6. Resend (Email service) - Create a Resend account and configure:

• RESEND_API_KEY="re_**********"
• RESEND_DOMAIN="carbon.ms" (or your domain, no trailing slashes or protocols)
• RESEND_AUDIENCE_ID="*****" (Optional - required for contact management in packages/jobs)

Resend is used for transactional emails (user invitations, email verification, onboarding). All three variables are stored in packages/auth/src/config/env.ts.

7. Novu (In-app notifications) - Create a Novu account and configure:

• NOVU_APPLICATION_ID="********************" (Client-side, public)
• NOVU_SECRET_KEY="********************" (Server-side secret, backend only)

Novu is used for in-app notifications and notification workflows. After standing up the application and tunnelling port 3000, sync your Novu workflows:

npm run novu:sync

This command syncs your Novu workflows with the Carbon application using the bridge URL.

Finally, start the apps and packages:

$ npm run dev
$ npm run dev:mes        # npm run dev in all apps & packages

After installation you should be able run the apps locally. | Application | URL | | --------------- | ------------------------------------------------------------------------------------------------------------------ | |