letsbe
/
kalei
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
kalei/docs/codex phase documents/phase-1-platform-foundation.md

5.1 KiB
Raw Blame History

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.