kalei/docs/codex phase documents/phase-1-platform-foundation.md

# Phase 1 - Platform Foundation

Duration: 2-3 weeks
Primary owner: Backend-first with mobile stub integration

## 1. Objective

Build a production-grade platform foundation:

- robust auth and session model
- entitlement checks for free vs paid plans
- core domain schema for Mirror, Turn, and Lens
- AI gateway scaffold with usage metering
- observability and error handling baseline

## 2. Entry Criteria

Phase 0 exit checklist must be complete.

## 3. Core Scope

## 3.1 API Module Setup

Implement service modules:

- auth
- profiles
- entitlements
- mirror (session/message skeleton)
- turn (request skeleton)
- lens (goal/action skeleton)
- ai_gateway
- usage_cost
- safety (precheck skeleton)

Each module needs:

- route handlers
- input/output schema validation
- service layer
- repository/data access layer
- unit tests

## 3.2 Identity and Access

Implement:

- email/password registration and login
- JWT access token (short TTL)
- refresh token rotation and revocation
- logout all sessions
- role model (at least `user`, `admin`)

Security details:

- hash passwords with Argon2id or bcrypt
- store refresh tokens hashed
- include device metadata per session

## 3.3 Entitlement Model

Implement plan model now, even before paywall UI is complete.

Suggested plan keys:

- `free`
- `prism`
- `prism_plus`

Implement gates for:

- turns per day
- mirror sessions per week
- spectrum access

Integration approach:

- no RevenueCat dependency
- ingest App Store Server Notifications directly
- ingest Google Play RTDN notifications directly
- maintain local entitlement snapshots as source of truth for authorization

## 3.4 Data Model (Phase 1 schema)

Create migrations for:

- users
- profiles
- subscriptions
- entitlement_snapshots
- turns
- mirror_sessions
- mirror_messages
- mirror_fragments
- lens_goals
- lens_actions
- ai_usage_events
- safety_events

Design requirements:

- every row has `created_at`, `updated_at` where relevant
- index by `user_id` and key query timestamp
- soft delete where legal retention requires it

## 3.5 AI Gateway Scaffold

Implement a strict abstraction now:

- provider adapter interface
- request envelope (feature, model, temperature, timeout)
- response normalization
- token usage extraction
- retry + timeout + circuit breaker policy

Do not expose provider SDK directly in feature modules.

## 3.6 Safety Precheck Skeleton

Implement now even if rule set is basic:

- deterministic keyword precheck
- safety event logging
- return safety status to caller

Mirror and Turn endpoints must call this precheck before generation.

## 3.7 Usage Metering and Cost Guardrails

Implement:

- per-user usage counters in Redis
- endpoint-level rate limit middleware
- AI usage event write on every provider call
- per-feature daily budget checks

## 3.8 Observability Baseline

Implement:

- structured logging with request IDs
- error tracking to GlitchTip
- latency and error metrics per endpoint
- AI cost metrics by feature

## 4. Detailed Build Sequence

Week 1:

1. Finalize schema and migration files.
2. Implement auth and profile endpoints.
3. Add integration tests for auth flows.

Week 2:

1. Implement entitlements and plan gating middleware.
2. Implement AI gateway interface and one real provider adapter.
3. Implement Redis rate limits and usage counters.

Week 3:

1. Implement Mirror and Turn endpoint skeletons with safety precheck.
2. Implement Lens goal and action skeleton endpoints.
3. Add complete observability hooks and dashboards.

## 5. API Contract Minimum For End Of Phase

Auth:

- `POST /auth/register`
- `POST /auth/login`
- `POST /auth/refresh`
- `POST /auth/logout`
- `GET /me`

Entitlements:

- `GET /billing/entitlements`
- webhook endpoints for App Store and Google Play billing event ingestion

Feature skeleton:

- `POST /mirror/sessions`
- `POST /mirror/messages`
- `POST /turns`
- `POST /lens/goals`

## 6. Testing Requirements

Minimum automated coverage:

- auth happy path and invalid credential path
- token refresh rotation path
- entitlement denial for free limits
- safety precheck path for crisis keyword match
- AI gateway timeout and fallback behavior

Recommended:

- basic load test for auth + turn skeleton endpoints

## 7. Phase Deliverables

Code deliverables:

- migration files for core schema
- API modules with tests
- Redis-backed rate limit and usage tracking
- AI gateway abstraction with one provider
- safety precheck middleware

Operational deliverables:

- GlitchTip configured
- endpoint metrics visible
- API runbook for local and staging

## 8. Exit Criteria

You can exit Phase 1 when:

- core auth model is stable and tested
- plan gating is enforced server-side
- Mirror/Turn/Lens endpoint skeletons are live
- AI calls only happen through AI gateway
- logs, metrics, and error tracking are active

## 9. Risks To Watch

- Risk: auth complexity balloons early.
  - Mitigation: keep v1 auth strict but minimal; defer advanced IAM.
- Risk: schema churn from feature uncertainty.
  - Mitigation: maintain a schema decision log and avoid premature optimization.
- Risk: provider coupling in feature code.
  - Mitigation: enforce gateway adapter pattern in code review.