Developer Getting Started

This guide walks you through setting up the StudioBrain development environment for contributing to the backend, frontend, or SDK.

Prerequisites

Tool	Version	Purpose
Rust	1.78+ (stable)	Backend server (sb-server, sb-cloud)
Node.js	20+	Frontend (Next.js), TypeScript SDK
pnpm	9+	Package manager for frontend
SQLite dev headers	3.40+	`libsqlite3-dev` on Debian/Ubuntu
Git	2.30+	Version control

Optional (for cloud development):

Tool	Version	Purpose
Docker	24+	Building container images
PostgreSQL client	15+	Cloud backend (YugabyteDB compat)
Python	3.12+	AI service, accounts service (legacy)

Clone the Repo

git clone https://github.com/BiloxiStudios/studiobrain-core.git
cd studiobrain-core

Backend (Rust)

The backend is a Rust workspace with three crates:

crates/
  sb-core/     — Pure types (Entity, Template, etc.)
  sb-server/   — Axum HTTP server (~100 endpoints)
  sb-storage/  — SQLite storage backend

Build

# Build the self-hosted server (SQLite backend)
cargo build -p sb-server --features sqlite
 
# Run tests
cargo test --workspace
 
# Run the server
JWT_SECRET=dev-secret \
DATABASE_URL=sqlite:///tmp/studiobrain-dev.db \
cargo run -p sb-server --features sqlite

The server starts on http://localhost:8000. First-run creates an empty SQLite database. Register the admin user with POST /api/auth/register.

Verify

# Health check
curl http://localhost:8000/api/health
 
# Register first user (creates admin)
curl -X POST http://localhost:8000/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email": "admin@local.dev", "password": "devpass123"}'
 
# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "admin@local.dev", "password": "devpass123"}'

Key Environment Variables

Variable	Default	Description
`JWT_SECRET`	(required)	HS256 signing key for self-hosted mode
`DATABASE_URL`	(required)	`sqlite:///path/to/db` or PostgreSQL URL
`BIND_ADDR`	`0.0.0.0:8000`	Listen address
`RUST_LOG`	`info`	Log level (`debug`, `info`, `warn`, `error`)
`CORS_ORIGINS`	same-origin	Comma-separated allowed origins

Frontend (Next.js)

The frontend is a Next.js 15 app with React 19, TypeScript, and Tailwind CSS.

cd frontend
 
# Install dependencies
pnpm install
 
# Start dev server
pnpm dev

The frontend starts on http://localhost:3100 and proxies /api/* to the backend at http://localhost:8000.

Configure API URL

The frontend connects to the backend via NEXT_PUBLIC_API_URL:

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:8000

If unset, the frontend assumes the API is served from the same origin (production behavior behind the Traefik ingress).

TypeScript SDK

The SDK (@biloxistudios/studiobrain-sdk) contains all shared business logic. It lives at packages/sdk/.

cd packages/sdk
 
# Install dependencies
pnpm install
 
# Run tests
pnpm test
 
# Build
pnpm build

The frontend consumes the SDK via a webpack alias in dev (no npm publish needed) and via npm in CI.

SDK Rules

The SDK is the canonical source of truth for pure business logic. When adding new logic:

Add the pure function to the SDK first
Write tests in the SDK
Consume it from the frontend via import
Backend (Rust) implementations must produce identical output for the same input

See the TypeScript SDK reference for the full module list.

Project Structure

studiobrain-core/
  crates/
    sb-core/          — Rust: pure types, no framework deps
    sb-server/        — Rust: Axum HTTP server
    sb-storage/       — Rust: SQLite backend
  backend/            — Python FastAPI (LEGACY, being decommissioned)
  frontend/           — Next.js 15 web frontend
  packages/
    sdk/              — TypeScript SDK (@biloxistudios/studiobrain-sdk)

What lives where

Change type	Location	Build
New API endpoint	`crates/sb-server/src/routes/`	`cargo build`
Entity type logic	`crates/sb-core/src/`	`cargo build`
Storage queries	`crates/sb-storage/src/`	`cargo build`
Frontend page/component	`frontend/src/`	`pnpm dev`
Business logic (validation, formatting)	`packages/sdk/src/`	`pnpm build`

Running the Full Stack Locally

# Terminal 1: Backend
JWT_SECRET=dev-secret \
DATABASE_URL=sqlite:///tmp/studiobrain-dev.db \
cargo run -p sb-server --features sqlite
 
# Terminal 2: Frontend
cd frontend && NEXT_PUBLIC_API_URL=http://localhost:8000 pnpm dev

Open http://localhost:3100 in your browser.

Docker (Production Build)

# Build the Rust backend image
docker build -t sb-server -f Dockerfile.backend .
 
# Build the frontend image
docker build -t sb-frontend -f frontend/Dockerfile frontend/
 
# Run with Docker Compose (if available)
docker compose up

Other Repos

If you are working on cloud, desktop, AI, or accounts, see the repo-specific setup guides:

Repo	Setup	Notes
studiobrain-cloud	Requires sb-server as Cargo git dependency	Cloud SaaS wrapper
studiobrain-app	`cargo tauri dev` from `packages/desktop/`	Embeds sb-server on port 7070
studiobrain-ai	`pip install -e .` + `cargo build` for PyO3 crates	Python + Rust hybrid
studiobrain-accounts	`pip install -e .` + `cd packages/accounts && pnpm dev`	Python FastAPI + Next.js

Next Steps

REST API Reference — Full endpoint documentation
Layout System Architecture — How entity forms are rendered
Widget Registry Reference — Available form widgets
Template Authoring — Creating custom entity types

Overview REST API Reference