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

# Phase 0 - Groundwork and Dev Environment

Duration: 1-2 weeks
Primary owner: Founder + coding assistant

## 1. Objective

Build a stable base so feature work can move fast without breaking:

- all required accounts are created
- local stack boots reliably
- repo structure and standards are in place
- CI checks run on every pull request

## 2. Prerequisites

- Read `docs/kalei-getting-started.md`
- Read `docs/kalei-system-architecture-plan.md`

## 3. Outcomes

By the end of Phase 0 you will have:

- local Postgres and Redis running via Docker
- mobile app bootstrapped with Expo
- API service bootstrapped with Fastify
- initial DB migration system in place
- lint, format, and test commands working
- CI pipeline validating every PR

## 4. Deep Work Breakdown

## 4.1 Access and Account Setup

Task list:

1. Set up Gitea (self-hosted or managed) for source control and CI.
2. Set up open-weight model serving accounts and endpoints (Ollama local, vLLM target host).
3. Create GlitchTip project for API and mobile error tracking.
4. Create PostHog self-hosted project for product analytics.
5. Set up DNS (PowerDNS self-hosted or managed DNS provider) and add domain.
6. Confirm Apple Developer and Google Play Console access (required for app distribution).

Deliverables:

- shared credential inventory (local secure password manager)
- documented secret naming convention

## 4.2 Repository and Branching Standards

Task list:

1. Define branch policy: `main`, short-lived feature branches.
2. Define PR checklist template.
3. Add CODEOWNERS or at least reviewer policy.
4. Add issue templates for bug and feature requests.

Deliverables:

- `CONTRIBUTING.md`
- `.gitea/pull_request_template.md` (or repository PR template equivalent)
- `.gitea/ISSUE_TEMPLATE/*` (or repository issue template equivalent)

## 4.3 Local Development Environment

Task list:

1. Install and verify Git, Node, npm, Docker, Expo CLI.
2. Add Docker compose for Postgres + Redis.
3. Create `.env.example` for API and mobile.
4. Add one-command local start script.

Deliverables:

- `infra/docker/docker-compose.yml`
- `services/api/.env.example`
- `apps/mobile/.env.example`
- root `Makefile` or npm scripts for local startup

## 4.4 API and Mobile Skeletons

Task list:

1. Create Fastify app with health endpoint.
2. Create Expo app with tabs template.
3. Add API client module to mobile app.
4. Show backend health status in app.

Deliverables:

- API running on local port
- mobile app able to read API response

## 4.5 Data and Migration Baseline

Task list:

1. Choose migration tool (for example, `node-pg-migrate`, `drizzle`, or `knex`).
2. Create first migration set for identity tables.
3. Add migration run and rollback commands.
4. Add seed command for local dev data.

Minimum initial tables:

- users
- profiles
- auth_sessions
- refresh_tokens

## 4.6 Quality and Automation Baseline

Task list:

1. Add ESLint + Prettier for API and mobile.
2. Add API unit test framework and one integration test.
3. Configure Gitea Actions (or Woodpecker CI) for lint + test.
4. Add commit hooks (optional but recommended) using `husky`.

Deliverables:

- passing CI on every push/PR
- at least one passing API integration test

## 5. Suggested Day-by-Day Plan

Day 1:

- account setup
- tooling install
- repo folder scaffold

Day 2:

- docker compose and env files
- API skeleton with `/health`

Day 3:

- Expo app setup
- mobile to API health call

Day 4:

- migration tooling and first migrations
- baseline seed script

Day 5:

- linting and tests
- CI setup
- first stable baseline commit

## 6. Validation Checklist

All items must be true:

- `docker compose` starts Postgres and Redis with no errors.
- API starts and `GET /health` returns 200.
- Mobile app loads and displays backend health.
- Migrations can run on clean DB and rollback at least one step.
- CI runs lint and tests successfully.

## 7. Exit Criteria

You can exit Phase 0 when:

- no manual setup surprises remain for a fresh machine
- all team members can run the stack locally in under 30 minutes
- baseline quality checks are automated

## 8. Platform exceptions

These are not open source, but required for shipping mobile apps:

- Apple App Store tooling and APIs
- Google Play tooling and APIs

## 9. Typical Pitfalls and Fixes

- Pitfall: unclear `.env` expectations.
  - Fix: complete `.env.example` files with comments.
- Pitfall: mobile app cannot reach local API on real device.
  - Fix: use machine LAN IP, not localhost, for device testing.
- Pitfall: migration drift.
  - Fix: never edit applied migration files; create a new migration.