Local development

Raidz is an npm monorepo with four workspaces and an isolated Docker runtime.

Requirements

Node.js >=22.13.0 <23
npm
Docker Engine and Compose plugin
GNU-compatible shell for the documented operator commands

Install and run

npm install
npm run dev

The domain package builds first because the API imports @raidz/domain. The development command then starts Next.js and Fastify concurrently.

Workspace scripts

Command	Purpose
`npm run dev`	Build domain, then start web and API development servers
`npm run lint`	Run every workspace lint script
`npm run typecheck`	Build domain and type-check workspaces
`npm test`	Build domain and run workspace tests
`npm run build`	Production-build domain, API, bot, and web
`npm run check`	Lint, type-check, test, and build
`npm run contracts:test`	Build isolated Foundry image and run contract tests
`npm run security:check`	Run project security checks
`npm run brand:export`	Export generated brand artifacts

Environment

Copy .env.example only for public, non-secret configuration. The important values are:

Variable	Meaning
`NEXT_PUBLIC_APP_URL`	Browser-visible application URL
`API_INTERNAL_URL`	Server-side web-to-API URL
`NEXT_PUBLIC_ROBINHOOD_CHAIN_ID`	Browser network, currently `4663`
`NEXT_PUBLIC_REOWN_PROJECT_ID`	Public Reown project identifier; injected at web build time
`NEXT_PUBLIC_RAIDZ_TOKEN_ADDRESS`	Must stay empty until verified deployment
`NEXT_PUBLIC_PONS_FACTORY_ADDRESS`	Must be populated from a current verified source
`DATABASE_URL`	PostgreSQL connection for identity and future marketplace state
`REDIS_URL`	Redis connection; deployed but not yet used by current API code

OAuth secrets, bot credentials, verifier keys, and wallet material must not enter .env, Compose output, source, test snapshots, or logs. Production uses *_FILE variables and read-only mounts.

Docker topology

docker compose -p raidz up --build
docker compose -p raidz ps
docker compose -p raidz logs --tail=200 web api

The base stack starts web, API, PostgreSQL, and Redis. analytics adds ClickHouse. integrations adds the Telegram bot. Resources are project-named and labeled owner=incubator-node and project=raidz.

Tests and fixtures

Web missions and creators in apps/web/components/data.ts are intentional fixtures and must remain labeled. API tests can inject an IdentityStore test double and disable migration. Contract tests run against local test tokens and addresses only.

Before submitting a change, run:

npm run check
npm run contracts:test
docker compose -p raidz config --quiet

If a change touches public copy, confirm pre-launch labels. If it touches economics or signatures, update domain tests, Solidity tests, and these docs together.

Contract-test dependency layout

contracts/Dockerfile.test copies node_modules/@openzeppelin/contracts into its Foundry image. The canonical clean install uses the tracked npm lockfile and materializes that path. A pnpm-style symlink whose target is excluded from the Docker build context can produce COPY failed; in that case, use the repository's documented npm install path in a clean dependency tree or update the container build deliberately rather than weakening .dockerignore broadly.