Prerequisites

Toolchain

Tool	Version	Notes
Node.js	≥ 20.9 (22.x recommended)	The API deploys on node:22-alpine; marketing requires >=20.9.
npm	11.x	Pinned via packageManager: npm@11.6.2 in the root package.json.
PostgreSQL	14+ (Supabase)	Any Postgres works; production uses Supabase's transaction pooler.
Git	any recent	—

Optional, depending on which app you work on:

Tool	For
Expo CLI / Android SDK + JDK 17	apps/mobile native builds
Docker	Reproducing the API's Alpine build locally
redis-cli	Inspecting / clearing rate-limit counters

Verifying your setup

node --version   # v20.9+ (v22 preferred)
npm --version    # 11.x
npx prisma --version

Repository layout

cropto/
├── apps/
│   ├── api/          Express + TypeScript backend (business logic, workers)
│   ├── web/          React 18 + Vite trading app (PWA)
│   ├── admin/        React 18 + Vite admin panel
│   ├── marketing/    Next.js 15 + Payload CMS 3 marketing site
│   └── mobile/       Expo / React Native app (Phase 2)
├── packages/
│   ├── types/        Shared TypeScript types / enums (@cropto/types)
│   ├── utils/        Shared utilities (@cropto/utils)
│   ├── api-client/   Shared typed API client (@cropto/api-client)
│   └── hooks/        Shared React hooks (@cropto/hooks)
├── prisma/
│   ├── schema.prisma Single schema — 40 models, 26 enums
│   ├── migrations/   47 tracked migrations
│   ├── seed.ts       Taxonomy tree + lookups seed
│   └── scripts/      One-shot maintenance scripts
├── docs/             This documentation site
└── package.json      npm workspaces root

Toolchain caveats (Windows)

The API container is Linux/musl (node:22-alpine), while local dev is often Windows. Running npm install on Windows over an existing node_modules can prune other platforms' optional native binaries (@img/sharp-*, @next/swc-*) from the lockfile, which then breaks the Alpine image at boot. If you touch dependencies:

# Re-sync the lockfile for ALL platforms without installing
npm install --package-lock-only
# Sanity check the musl sharp binary is still present
grep sharp-linuxmusl-x64 package-lock.json

The API Dockerfile smoke-tests require('sharp') right after npm ci so this class of bug fails the build, not production boot.