Developer Setup Guide

Welcome to the Business M Developer Guide. This runbook walks you through the simplest path to configure your local development environment and run the monolithic core.

1. Prerequisites

Verify that your development machine has the following tools installed:

Operating System: Linux, macOS, or Windows (via WSL2).
Python 3.12+: Asynchronous runtime environment.
uv: Ultra-fast Python package and environment manager. Install uv.
Node.js LTS (v24): Required to compile frontends.
pnpm: Node package manager (npm install -g pnpm).
PostgreSQL 14+: You can run this natively or via Docker (see Step 2).

2. Workspace Initialization

First, clone the monorepo and navigate to the project root.

2.1 Clone the Repository

git clone https://gitlab.com/castlecraft/business-m
cd business-m

2.2 Install Dependencies

Install both Python and Node.js dependencies across the entire workspace:

uv sync
pnpm install

3. Choose Your Architecture Path

Business M can be run as a unified monolith or as distributed macroservices. Choose the path that matches your development goal.

Option A: Monolithic (Indie) Mode (Recommended Quick Start)

The monolithic track is the simplest way to get the entire Business M stack running locally within a single process. It relies on standard PostgreSQL and Redis.

1. Provision Infrastructure Start the background database engines using Docker Compose:

docker compose -f deploy/compose/dev/dev.compose.yml up -d

Note: This creates the postgres user and database automatically. If you prefer not to use Docker, ensure native PostgreSQL is running on port 5432 and run createdb business_m.

2. Configure & Migrate Navigate to the core application folder, set up your .env, and sync the schema:

cd apps/business-m
cp .env.example .env
uv run m migrate sync --apps business_m

3. Launch the Development Server Start the monolithic orchestrator:

uv run m dev

Both the backend API and frontend Vite server will start. Open http://localhost:5173 in your browser.

Option B: Macroservice (Enterprise) Mode

The macroservice track is used for high-throughput enterprise deployments. It runs domain logic as decoupled, out-of-process services communicating over NATS, and utilizes specialized engines like TigerBeetle and KurrentDB.

1. Provision Distributed Infrastructure Start the expanded infrastructure stack:

docker compose -f deploy/compose/dev/dev.compose.yml \
               -f deploy/compose/dev/macroservices.compose.yml up -d

2. Configure & Migrate Navigate to the core application folder and synchronize the schemas for the distributed databases:

cd apps/business-m
cp .env.example .env
uv run m migrate sync --apps business_m

3. Launch the Distributed Services Start the decoupled macroservices orchestrator:

uv run m dev --procfile=macroservices.Procfile --env-file=macroservices.env --no-backend --port=8000

Open http://localhost:5173 in your browser to interact with the distributed system.

4. Important `m dev` CLI Flags

The m dev orchestrator command can be customized using the following flags to suit your development needs:

--port / --frontend-port: Override the default backend (8888) or frontend (5173) ports.
--no-backend / --no-frontend: Disable starting the respective service. Extremely useful if you only want to work on one side of the stack (e.g., UI only).
--enable-worker / --enable-scheduler: Start background processors alongside your API. Required if you are testing asynchronous task queues or scheduled cron jobs locally.
--procfile / --env-file: Override the default process manager definitions and environment variables. (This is how we switch to Macroservice mode).
--studio: Automatically boot up the database studio on port 9999 to visually inspect your schema and records.

5. Development Workflows

The m CLI provides built-in code scaffolding templates and verification tools.

Scaffolding New Components

m new app my_custom_app
m new doctype MyFeatureSchema --app business_m
m new frontend my_custom_frontend

Testing and Code Quality

Ensure your code meets the quality standards before submitting a merge request:

# Run tests
uv run pytest

# Format, Lint, and Typecheck
uv run m format
uv run m lint
uv run m typecheck