kalei/docs/kalei-getting-started.md

# Kalei Getting Started Guide (Beginner Friendly)

Last updated: 2026-02-10
Audience: First-time app builders

This guide explains the groundwork you need before coding, then gives you the exact first steps to start building Kalei.

Reference architecture: `docs/kalei-system-architecture-plan.md`

## 1. What You Are Building

Kalei is a mobile-first mental wellness product with four product pillars:

- Mirror: freeform writing with passive AI fragment detection.
- Turn (Kaleidoscope): structured AI reframing.
- Lens: goals, daily actions, and affirmations.
- Spectrum (Phase 2): weekly and monthly insight analytics.

At launch, your implementation target is:

- Mobile app: React Native + Expo.
- Backend API: Node.js + Fastify.
- Data: PostgreSQL + Redis.
- Source control and CI: Gitea + Gitea Actions (or Woodpecker CI).
- AI access: provider-agnostic AI Gateway using open-weight models (Ollama for local dev, vLLM for staging/prod).
- Billing and entitlements: self-hosted entitlement service (direct Apple App Store + Google Play verification, no RevenueCat dependency).

## 2. How To Use This Document Set

Read in this order:

1. `docs/kalei-getting-started.md` (this file)
2. `docs/codex phase documents/README.md`
3. `docs/codex phase documents/phase-0-groundwork-and-dev-environment.md`
4. `docs/codex phase documents/phase-1-platform-foundation.md`
5. `docs/codex phase documents/phase-2-core-experience-build.md`
6. `docs/codex phase documents/phase-3-launch-readiness-and-hardening.md`
7. `docs/codex phase documents/phase-4-spectrum-and-scale.md`

## 3. Groundwork Checklist (Before You Write Feature Code)

## 3.1 Accounts You Need

Create these accounts first so you do not block yourself later.

Must have for early development:

- Gitea (source control and CI)
- Apple Developer Program (iOS distribution, required)
- Google Play Console (Android distribution, required)
- DNS provider account (or self-hosted DNS using PowerDNS)

Strongly recommended now (not later):

- GlitchTip (open-source error tracking)
- PostHog self-hosted (open-source product analytics)
- Domain registrar account (for `kalei.ai`)

## 3.2 Local Tools You Need

Install this baseline stack:

- Git
- Node.js LTS (via `nvm`, recommended)
- npm (bundled with Node) or pnpm
- Docker Desktop (for PostgreSQL + Redis locally)
- VS Code (or equivalent IDE)
- Expo Go app on your phone (iOS/Android)
- Ollama (local open-weight model serving)

Install and verify:

```bash
# Git
git --version

# nvm + Node LTS
nvm install --lts
nvm use --lts
node -v
npm -v

# Docker
docker --version
docker compose version

# Expo CLI (optional global; npx is also fine)
npx expo --version

# Ollama
ollama --version
```

## 3.3 Decide Your Working Model

Set these rules now:

- Work in short feature slices with demoable outcomes.
- Every backend endpoint gets at least one automated test.
- No direct AI calls from client apps.
- No secrets in the repo, ever.
- Crisis-level text is never reframed.

## 4. Recommended Monorepo Structure

If you are starting from scratch, use this layout:

```text
Kalei/
  apps/
    mobile/
  services/
    api/
    workers/
  packages/
    shared/
  infra/
    docker/
    scripts/
  docs/
```

Why this structure:

- Keeps mobile and backend isolated but coordinated.
- Lets you share schemas/types in `packages/shared`.
- Keeps infra scripts in one predictable place.

## 5. Step-By-Step Initial Setup

These are the first practical steps for week 1.

## Step 1: Initialize folders

```bash
mkdir -p apps/mobile services/api services/workers packages/shared infra/docker infra/scripts
```

## Step 2: Bootstrap the mobile app

```bash
npx create-expo-app@latest apps/mobile --template tabs
cd apps/mobile
npm install
cd ../..
```

## Step 3: Bootstrap the API service

```bash
mkdir -p services/api && cd services/api
npm init -y
npm install fastify @fastify/cors @fastify/helmet @fastify/sensible zod dotenv pino pino-pretty pg ioredis
npm install -D typescript tsx @types/node vitest supertest @types/supertest eslint prettier
npx tsc --init
cd ../..
```

## Step 4: Bring up local PostgreSQL and Redis

Create `infra/docker/docker-compose.yml`:

```yaml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: kalei
      POSTGRES_PASSWORD: kalei
      POSTGRES_DB: kalei
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  pg_data:
  redis_data:
```

Start services:

```bash
docker compose -f infra/docker/docker-compose.yml up -d
```

## Step 5: Create environment files

Create:

- `services/api/.env`
- `apps/mobile/.env`

API `.env` minimum:

```env
NODE_ENV=development
PORT=8080
DATABASE_URL=postgres://kalei:kalei@localhost:5432/kalei
REDIS_URL=redis://localhost:6379
JWT_ACCESS_SECRET=replace_me
JWT_REFRESH_SECRET=replace_me
AI_PROVIDER=openai_compatible
AI_BASE_URL=http://localhost:11434/v1
AI_MODEL=qwen2.5:14b
AI_API_KEY=local-dev
GLITCHTIP_DSN=replace_me
POSTHOG_API_KEY=replace_me
POSTHOG_HOST=http://localhost:8000
APPLE_SHARED_SECRET=replace_me
GOOGLE_PLAY_PACKAGE_NAME=com.kalei.app
```

Mobile `.env` minimum:

```env
EXPO_PUBLIC_API_BASE_URL=http://localhost:8080
EXPO_PUBLIC_ERROR_TRACKING_DSN=replace_me
```

## Step 6: Create your first backend health endpoint

Create `/health` returning status, uptime, and version. This is your first proof that the API is running.

## Step 7: Connect mobile app to backend

Add a tiny service function in mobile that calls `/health` and shows the result on screen.

## Step 8: Add migrations baseline

Create migration folders and your first migration for:

- users
- profiles
- auth_sessions
- refresh_tokens

Add a migration script and run it on local Postgres.

## Step 9: Set up linting, formatting, and tests

At minimum:

- API: `npm run lint`, `npm run test`
- Mobile: `npm run lint`

## Step 10: Push a clean baseline commit

Your first stable commit should include:

- mobile app runs
- API runs
- db and redis run in Docker
- health endpoint tested
- env files templated

## 6. Non-Negotiable Ground Rules

These reduce rework and production risk.

- API-first contracts: Define backend request/response schema first.
- Version prompts: Keep prompt templates in source control with version tags.
- Idempotency: write endpoints should support idempotency keys.
- Structured logs: every request gets a request ID.
- Safety-first branching: crisis path is explicit and tested.

## 7. Open-Source-First Policy

Default to open-source tools unless there is a hard platform requirement.

Open-source defaults for Kalei:

- Git forge and CI: Gitea + Gitea Actions (or Woodpecker CI)
- Error tracking: GlitchTip
- Product analytics: PostHog self-hosted
- AI serving: Ollama (local), vLLM (staging/prod)
- Runtime and data: Fastify, PostgreSQL, Redis

Unavoidable non-open-source dependencies:

- Apple App Store distribution and StoreKit APIs
- Google Play distribution and Billing APIs
- APNs and FCM for push delivery

## 8. What "Done" Looks Like For Groundwork

Before Phase 1 starts, you should be able to demonstrate:

- Local stack boot with one command (`docker compose ... up -d`).
- API starts with no errors and serves `/health`.
- Mobile app opens and calls API successfully.
- Baseline DB migrations run and rollback cleanly.
- One CI pipeline runs lint + tests on pull requests.

## 9. Common Beginner Mistakes (Avoid These)

- Building UI screens before backend contracts exist.
- Calling AI provider directly from the app.
- Waiting too long to add tests and logs.
- Keeping architecture only in your head (not in docs).
- Delaying safety and privacy work until late phases.

## 10. Recommended Weekly Rhythm

Use this cycle every week:

1. Plan: define exact outcomes for the week.
2. Build: complete one vertical slice (API + mobile + data).
3. Verify: run tests, manual QA, and failure-path checks.
4. Demo: produce a short demo video for your own review.
5. Retrospective: capture blockers and adjust next week.

## 11. Next Step

Start with:

- `docs/codex phase documents/phase-0-groundwork-and-dev-environment.md`

Then execute each phase in order.