Developer Setup Guide

Welcome to the Business M Developer Guide. This runbook walks you through configuring your local development environment to run both our modular monolithic core and decoupled macroservice configurations.

1. Local Prerequisites

Verify that your development machine has the following tools installed:

Operating System: Linux (Ubuntu/Debian recommended), macOS, or Windows (WSL2 required).
Python 3.12+: Asynchronous runtime environment.
uv: Ultra-fast Python package and environment manager. Install uv.
Node.js LTS (v24): Required to compile frontends and Vite federation bundles.
pnpm: Required to manage node packages (npm install -g pnpm).
PostgreSQL LTS: Relational storage engine.

2. Workspace Initialization

2.1 Clone the Workspace

Clone the monorepo from GitLab and navigate to the workspace root:

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

2.2 Initialize Python Dependencies

Setting up your virtual environment and installing all package dependencies happens in a single command:

uv sync

This creates a unified .venv virtual environment in the workspace root and installs dependencies for all sub-libraries (libs/*) and applications (apps/*) in editable mode.

2.3 Virtual Environment Activation

Bash / Zsh:
Terminal window
```
source .venv/bin/activate
```
Fish Shell:
Terminal window
```
. ./.venv/bin/activate.fish
```

2.4 Initialize Frontend Packages

Install workspace-wide node packages:

pnpm install

3. Provisioning the Engine Layer & Services

3.1 Quick Setup: Docker Compose Engine Stack

To simplify development, we package the entire localized infrastructure Engine Layer (including PostgreSQL for relational metadata, Redis for state caching, and NATS for event messaging) into a single, light Docker Compose context.

To spin up all services instantly, run:

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

Manual database creation is not required. All domain applications automatically share this unified PostgreSQL instance, and their tables will not conflict because they are dynamically isolated and prefixed by their respective domain modules.

Extensible & Pluggable Engines (e.g., TigerBeetle): High-performance infrastructure engines like TigerBeetle (used for ultra-fast, double-entry financial ledger operations) are fully pluggable. The default local development stack only requires PostgreSQL, Redis, and NATS (included in dev.compose.yml) to run all monolith features and standard test suites.

You do not need to run TigerBeetle unless you are specifically developing or testing high-scale distributed ledger sub-systems. If you do need TigerBeetle locally, you can launch our pre-configured TigerBeetle instance instantly in the background on port 3000 without any native installation by running:

docker compose -f macroservices.compose.yml up -d tigerbeetle

3.2 Fallback: Native Host Service Deployment

If running Docker is a challenge on your development machine (e.g., due to specific Windows / WSL2 virtualization constraints or resource limits), you can easily choose to run the engines natively on your host:

Install the Core Engines:
- PostgreSQL: Install PostgreSQL locally and verify the service is running.
- Redis: Install and start the Redis server locally.
- NATS Server: Install and launch the NATS server.
Verify Ports: Ensure these native processes are active on their standard ports:
- PostgreSQL: 5432
- Redis: 6379
- NATS: 4222

No database schema configurations are needed; our migrations automatically target these default local ports.

3.3 Environment Variable Configurations

For local execution, the environment variables and multi-process runners are pre-configured:

Use monolith.env and monolith.Procfile for monolithic (Indie) mode.
Use macroservices.env and macroservices.Procfile for distributed (Enterprise) macroservice mode.

No manual .env file editing or database configuration is necessary for the default local environment.

4. Launching the Local Server

Launch the development orchestrator CLI specifying the desired deployment track:

Option A: Monolithic (Indie) Mode

To run all modules inside a single process:

m dev --procfile=monolith.Procfile --env-file=monolith.env --no-backend --port=8000

Option B: Distributed (Enterprise) Mode

To run domain services as decoupled out-of-process macroservices:

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

Development Portal URL: http://localhost:5173 (The host Vite development server remains the same on port 5173 for both monolithic and macroservice development modes for development)

5. Standard Developer Workflows

The m CLI provides built-in code scaffolding templates.

5.1 Scaffolding New Components

Scaffold a new App:
Terminal window
```
m new app my_custom_app
```

Scaffold a new DocType model:

m new doctype MyFeatureSchema --app business_m

Scaffold a new frontend panel:
Terminal window
```
m new frontend my_custom_frontend
```

5.2 Running the Test Suites

To execute unit and integration test suites workspace-wide:

uv run pytest

To run localized tests within a specific sub-package:

cd libs/finance
uv run pytest

6. Code Style & Verification

We enforce quality standards via ruff for Python files:

uv run ruff check .
uv run ruff format .