8.0 KiB

Raw Blame History

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:

docs/kalei-getting-started.md (this file)
docs/codex phase documents/README.md
docs/codex phase documents/phase-0-groundwork-and-dev-environment.md
docs/codex phase documents/phase-1-platform-foundation.md
docs/codex phase documents/phase-2-core-experience-build.md
docs/codex phase documents/phase-3-launch-readiness-and-hardening.md
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:

# 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:

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

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

Step 2: Bootstrap the mobile app

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

Step 3: Bootstrap the API service

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:

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:

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:

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:

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:

Plan: define exact outcomes for the week.
Build: complete one vertical slice (API + mobile + data).
Verify: run tests, manual QA, and failure-path checks.
Demo: produce a short demo video for your own review.
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.

8.0 KiB Raw Blame History