Developer Onboarding

Get your development environment set up and running.

Prerequisites

Node.js 18+
pnpm 9.15+
Docker (for Neo4j and Redis)

Quick Start

# Clone and install
git clone <repository-url>
cd platform
pnpm install

# Start databases
docker compose up -d

# Run migrations
pnpm db migrate

# Start development
pnpm dev

The web app runs at http://localhost:3000.

Key Commands

Command	Description
`pnpm dev`	Start all apps in development mode
`pnpm build`	Build all packages and apps
`pnpm lint`	Run Biome linting
`pnpm lint:fix`	Auto-fix lint issues
`pnpm typecheck`	TypeScript validation
`pnpm test`	Run all tests
`pnpm codegen`	Generate GraphQL types

Monorepo Structure

/
├── apps/
│   ├── web/                 # Main Next.js 16 application
│   ├── storybook/           # Component development environment
│   └── local-auth0/         # Local Auth0 mock server
├── packages/
│   ├── core/                # Shared business logic (Clean Architecture)
│   ├── luz/                 # UI component library
│   └── typescript-config/   # Shared TypeScript configuration
└── turbo.json               # Turbo task configuration

Package Dependencies

apps/web
├── @repo/core      (use cases, repositories, types)
└── @repo/luz       (UI components)

packages/luz        (standalone)
packages/core       (standalone)

Import Patterns

// Core package (business logic)
import {
  CreateTransaction,           // Use case
  OrganisationRepository,      // Repository
  NotFoundError,               // Domain error
} from '@repo/core';

// Luz package (UI components)
import {
  LayoutContainer,
  Stack,
  DataBlock,
  BigTabs,
} from '@repo/luz';

// Server actions
import { createServerAction } from 'zsa';
import { useServerAction } from 'zsa-react';

File Naming

Kebab-case for all files: create-transaction.ts, modern-slavery.tsx
Co-located actions: page.tsx + actions.ts in same folder
Context files: [feature]-context.tsx

Common Gotchas

Issue	Solution
Dynamic params in Next.js 16	Always `await params` and `await searchParams`
Data loading in useEffect	Load data in Server Components instead
Prop drilling	Use Context or composition
Server Actions too complex	Keep thin: Auth → Validate → Use Case → Revalidate

Next Steps

Topic	Link
System architecture	Architecture
How domains connect	Domain Model
UI components	Luz or run `pnpm --filter storybook dev`
Coding patterns	Component Patterns
Testing	Testing Guide

On this page