Objectives

  • Ship a passwordless login experience that supports students (AI coaches operate as system services) while preparing for future admin roles.
  • Capture user preferences (display name, wealth focus, preferred AI coaches placeholder) and lay the groundwork for profile-driven personalization.
  • Let users bookmark and rate blog posts, surfacing a personalized "My Favorites" dashboard the AI coach pipeline can reference during sessions.
  • Instrument the foundation: database migrations, audit logging, analytics events, and environment configuration.

Functional Scope

Authentication & Account Lifecycle

  • Implement passwordless email login via NextAuth (or Supabase Auth) with session persistence.
  • Create onboarding checklist that collects minimal profile data (name, role, time zone) and stores it in the users table.
  • Support role flags (student, admin, system_service) to unlock targeted experiences later without requiring human coach accounts.
  • Provide account management: update profile, revoke sessions, delete account (soft delete plus GDPR-ready purge queue).

Personalized Home & Favorites

  • Add a protected /coach/home route that greets the logged-in user and summarizes their activity.
  • Introduce a favorites data model (favorites table) capturing user_id, post_slug, rating, and optional notes.
  • Enable inline "Favorite" and "Rate" controls on existing blog posts for authenticated users (client component with optimistic updates).
  • Surface a "My Favorites" page with filters (by wealth pillar tag, rating) and aggregated insights (top-rated categories, recently favorited posts).
  • Allow AI coaching agents (with explicit consent controls) to query a student’s favorites to ground future sessions.

Data Model & Persistence

  • Provision Postgres tables: users, sessions (auth), user_profiles, favorites, and audit_logs.
  • Add seed script for default wealth pillars and AI coach personas (even if selection UI ships later).
  • Define Prisma/Drizzle schemas and Zod validators for auth responses, profile payloads, and favorite mutations.
  • Create a migration playbook (local + production) and document rollback strategy.

Analytics, Observability & Ops

  • Emit analytics events for login success, onboarding completion, favorite/ratings interactions, and account edits.
  • Implement structured logging with request IDs to trace personalization actions.
  • Configure feature flags so new UI elements (favorites, ratings) can be rolled out gradually.
  • Document environment variables in .env.example (email provider, database URL, encryption keys).

Technical Considerations

  • Use server actions or API routes for favorites mutations to guarantee consistency and enforce rate limits.
  • Cache favorite counts/ratings per post via incremental static regeneration or edge caching to avoid hot-spot reads.
  • Guard against spam/abuse: limit favorites per user per minute, require verified email before enabling ratings.
  • Ensure accessibility: keyboard-triggerable favorite buttons, ARIA labels for rating stars, and mobile-friendly dashboard layout.
  • Plan for localization by keeping copy in translation-ready structures.

Multi-Agent Workstream

| Agent | Responsibilities | Deliverables | | --- | --- | --- | | Auth Specialist | Configure NextAuth, build onboarding flow, implement session management and account deletion. | Auth routes, profile forms, tests. | | Personalization Curator | Design favorites UI, personalized dashboard, and AI context surfaces. | React components, server actions, UX specs. | | Database Engineer | Create migrations, seeds, and data access layer for users/favorites/audit logs. | Migration scripts, schema docs. | | Analytics Lead | Instrument events, configure feature flags, and set up dashboards (e.g., PostHog, Segment). | Analytics schema, monitoring checklist. | | DevOps Steward | Manage environment setup, secret storage, and deployment guardrails. | .env.example, runbook, CI checks. |

Exit Criteria

  • Users can log in with email magic link, complete onboarding, and land on a personalized /coach/home route.
  • Favorite/ratings interactions persist to the database, update analytics, and render on the "My Favorites" dashboard.
  • AI coaching agents (with permission) can access a specific student’s favorites and ratings through secured service APIs.
  • Database migrations and seeds run successfully in local, staging, and production environments.
  • Observability checks confirm audit logging and analytics coverage for all major actions.

Risks & Mitigations

| Risk | Mitigation | | --- | --- | | Email deliverability issues for passwordless login. | Support fallback OTP codes, monitor bounce rates, allow admin to manually verify accounts. | | Favorites data skewing analytics due to accidental clicks. | Implement undo/snackbar, require explicit star rating for analytics dashboards, add debounce. | | Unauthorized access to student favorites. | Enforce row-level security or server-side role checks before exposing student data; log access attempts. | | Schema drift across environments. | Automate migrations in CI, block deploy if pending migrations exist. |

Dependencies & Notes

  • Requires email provider credentials (e.g., SendGrid) and database provisioning before feature work begins.
  • Coordinate with design to align favorites UI with existing blog aesthetic.
  • Provide API contracts for favorites/ratings to future mobile clients.
  • Share onboarding data (wealth focus) with Phase 2 team to pre-populate AI coach selection defaults.