kalei/docs/build-phases/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.