Getting Started

Getting Started

Tutorial — day-0 setup for a new dev or AI agent.

Prerequisites

• Node.js 22+ (repo’s engines pin)
• pnpm 10+ (enable via corepack enable)
• Docker + Docker Compose (local services)
• Expo Go app on a physical phone (optional, for live mobile testing)

Clone + install

git clone git@github.com:aciDrums7/ideony.git
cd ideony
corepack enable
pnpm install

Local services

pnpm docker:up

Starts: PostgreSQL (5433), Redis (6379), MinIO (9000/9001), Mailpit (1025/8025).

Environment variables

cp apps/api/.env.example apps/api/.env
cp apps/mobile/.env.example apps/mobile/.env

Fill in:

• CLERK_SECRET_KEY + CLERK_PUBLISHABLE_KEY (ask team or use dev Clerk app)
• STRIPE_SECRET_KEY (test-mode key)
• NOVU_API_KEY (EU region — see ./infrastructure.md)
• DATABASE_URL=postgresql://postgres:postgres@localhost:5433/ideony
• REDIS_URL=redis://localhost:6379

Database

cd apps/api
pnpm prisma migrate dev
pnpm prisma generate

Seed w/ demo data (10 parent + 36 child categories, demo consumer + pro):

pnpm seed

Run dev mode

pnpm dev    # from repo root — starts all apps

Or individually:

pnpm -F @ideony/api dev      # NestJS on :3001, Swagger at /api-docs
pnpm -F @ideony/mobile dev   # Expo dev server (press `i` iOS, `a` Android, `w` web)

Run tests

pnpm test             # all unit tests
pnpm test:e2e         # Playwright (requires dev servers running)
pnpm -F @ideony/api test:e2e   # API integration tests

Verify setup

1. http://localhost:3001/health → {status:"ok"}
2. http://localhost:3001/api-docs → Swagger UI w/ ~30 routes
3. http://localhost:8081 → Expo Metro bundler
4. Open Expo Go, scan the QR code → consumer welcome tour should render

Next reads

• architecture.md — what talks to what
• design-system.md — tokens, fonts, bans (critical before writing UI)
• testing.md — how to add tests
• status.md — what’s in flight
• ../CLAUDE.md — conventions + gotchas (critical if you’re an AI agent)

Troubleshooting

Symptom	Fix
pnpm install fails on @rnmapbox/maps	Install git-lfs (brew install git-lfs)
Metro build has stale env vars	rm -rf $TMPDIR/metro-cache or run expo start --clear
Prisma migration hangs	Check pnpm docker:ps — Postgres container healthy?
Clerk typed API errors	Use create() → prepareFirstFactor() → attemptFirstFactor() → setActive() (ADR-0005)
White screen in web build	Font 404 → see ./design-system.md on non-blocking font load

Getting help

• Check ./decisions/ before re-litigating a tech choice
• Check ./specs/ before designing a new feature
• Open an issue for anything not covered