236 lines
5.1 KiB
Markdown
236 lines
5.1 KiB
Markdown
# 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.
|