resolutionflow/docs/archive/2026-02-12-admin-invite-user-mgmt.md

Admin Panel: Invite Codes + User Management Enhancement

Date: 2026-02-12 Status: Proposed — Combined Plan

---

Summary

Enhance admin capabilities to:

1. Create invite codes tied to plans (free, pro, team) with optional trial durations.
2. Send invite emails via Resend (best-effort, non-blocking).
3. Apply invite-assigned plan/trial on registration.
4. Give admins a detailed user management view with subscription, session, and audit context.
5. Support admin subscription actions (change plan, extend/start trial).
6. Auto-downgrade expired trials during authenticated access checks.

---

Goals

• Remove manual invite-code sharing workflow.
• Support controlled beta onboarding with plan + trial at invite level.
• Enable operational admin workflows for account/subscription lifecycle.
• Keep backward compatibility where practical and avoid unsafe breaking changes.

---

Non-Goals

• Stripe billing workflow redesign.
• Full historical pagination for user-detail sessions/audits in this iteration.
• Rework of account invite (/accounts/me/invites) flow.

---

Key Decisions Locked

Decision	Choice	Rationale
Invite API path	Standardize on /invites	Already in use (router = APIRouter(prefix="/invites")). Update CLAUDE.md which incorrectly references /invite-codes.
User detail endpoint	Enrich existing GET /admin/users/{id}	One endpoint, richer response. No reason for admin to get a "lite" version.
Invite email matching	Advisory only (no strict enforcement)	The invite code itself is the security gate. Email is for admin tracking. Strict matching creates friction during beta.
Invite plan/trial application	Applies whenever a valid invite code is provided, even if REQUIRE_INVITE_CODE=false	Ensures plan/trial always carries through regardless of registration policy.
Trial duration bounds	1–90 days	90 days covers any realistic beta period. Protects against typos. Admin can always extend after expiry.
Extend trial behavior	May convert non-trialing subscriptions to trialing	Admin should have maximum control. Covers scenarios like forgotten trial assignment or second chances.
User detail payload	Recent summaries (latest 10 sessions + 10 audit logs) + total counts	Balances useful at-a-glance admin view with response performance. Full history via future paginated endpoints.

---

Phase 1: Database Migration (030)

New file: backend/alembic/versions/030_enhance_invite_codes.py (down revision 029)

Add columns to invite_codes:

• email: String(255), nullable, indexed.
• assigned_plan: String(50), non-null, server default 'free'.
• trial_duration_days: Integer, nullable.
• email_sent_at: DateTime(timezone=True), nullable.

Database constraints:

• assigned_plan IN ('free', 'pro', 'team').
• trial_duration_days IS NULL OR trial_duration_days BETWEEN 1 AND 90.
• Consistency guard: assigned_plan = 'free' implies trial_duration_days IS NULL.

Update: backend/app/models/invite_code.py

• Add mapped columns for all new fields.
• Add computed properties:
  • has_trial: bool — trial_duration_days is not None and > 0
  • email_sent: bool — email_sent_at is not None

---

Phase 2: Resend Email Integration

New file: backend/app/core/email.py

• EmailService class with send_invite_email(to_email, code, plan, trial_days, signup_url) -> bool.
• Returns False if RESEND_API_KEY not set (graceful degradation).
• Catches provider failures, returns False, logs warning/error.
• Never blocks invite creation (best-effort delivery).

New file: backend/app/templates/invite_email.html

• Branded HTML email: monochrome design, ResolutionFlow logo, CTA button.
• Shows invite code, plan name, trial duration if applicable, signup link.

Update: backend/app/core/config.py

• Add RESEND_API_KEY: Optional[str] = None
• Add FROM_EMAIL: str = "ResolutionFlow <invites@resolutionflow.com>"
• Add email_enabled computed property.

Update: backend/requirements.txt — add resend package.

Env vars required: RESEND_API_KEY, FROM_EMAIL (has default).

Prerequisite: DNS records (SPF, DKIM) must be configured in Resend for resolutionflow.com domain before production email delivery will work.

---

Phase 3: Backend Schemas + Endpoints

3a. Invite Code Schemas

Update: backend/app/schemas/invite_code.py

InviteCodeCreate — add fields:

• email: Optional[EmailStr]
• assigned_plan: Literal['free', 'pro', 'team'] = 'free'
• trial_duration_days: Optional[int] (validated 1–90)

InviteCodeResponse — add fields:

• email, assigned_plan, trial_duration_days, email_sent_at
• Computed flags: has_trial, email_sent

3b. Invite Endpoints

Update: backend/app/api/endpoints/invite.py

• POST /invites — accept new fields (email, assigned_plan, trial_duration_days).
  • Create invite with plan/trial/email metadata.
  • If email provided, attempt send via EmailService.
  • On send success: set email_sent_at.
  • On send failure: invite still returns 201.
  • Add audit log entry for invite creation with delivery result.
• Keep GET /invites, DELETE /invites/{code}, GET /invites/validate/{code} behavior compatible.

3c. Registration Plan Assignment

Update: backend/app/api/endpoints/auth.py (registration endpoint, around lines 178–183)

• If invite code is supplied and valid, load it and apply invite plan/trial regardless of REQUIRE_INVITE_CODE setting.
• For non-account-invite registrations:
  • Create subscription with plan = invite_code.assigned_plan (fallback 'free').
  • If trial_duration_days is set:
    • status = 'trialing'
    • current_period_start = now
    • current_period_end = now + trial_duration_days
  • Else: status = 'active'.
• Preserve existing account-invite join flow behavior.
• Mark invite as used after user creation.

3d. Admin Subscription + User Detail Endpoints

Update: backend/app/api/endpoints/admin.py

Enrich GET /admin/users/{id} response to include:

• Base user fields (name, email, role, active status).
• Account summary (account name, display code).
• Subscription summary (plan, status, trial end date).
• Recent sessions: latest 10 + total count.
• Recent audit logs: latest 10 + total count.
• Invite code used summary (code, assigned plan, who created it).

Add new endpoints:

• PUT /admin/users/{id}/subscription/plan — change user's plan.
• PUT /admin/users/{id}/subscription/extend-trial — add days to trial, or convert to trialing if not already.

Both endpoints should create audit log entries.

3e. Trial Expiry Check

Update: backend/app/api/deps.py — in get_current_active_user

• Check account subscription status.
• If status = 'trialing' and current_period_end < now:
  • Set plan = 'free', status = 'active'.
  • Clear/normalize trial period fields.
  • Commit before returning user.

Note: This is a lightweight login-time check. Users with active JWT sessions will retain access until token refresh. Acceptable for beta; revisit if stricter enforcement needed later.

---

Phase 4: Backend Schema Additions

Check first: Verify whether backend/app/schemas/subscription.py already exists. If it does, extend it. If not, create it.

Schemas needed in backend/app/schemas/subscription.py:

• SubscriptionPlanUpdate — for plan change requests.
• ExtendTrialRequest — for trial extension requests.
• SubscriptionResponse — for subscription state in responses.

New file: backend/app/schemas/user_detail.py

• AccountSummary
• SessionSummary
• AuditLogSummary
• InviteCodeUsedSummary
• UserDetailResponse (superset response for enriched /admin/users/{id})

---

Phase 5: Frontend Types + API Client

Update: frontend/src/types/admin.ts

• Enhanced InviteCodeResponse with email, plan, trial, email-sent fields.
• New types: UserDetail, SubscriptionDetail, SessionSummary, AuditLogSummary, AccountSummary.

Update: frontend/src/api/admin.ts

• Ensure invite endpoints target /invites (not /invite-codes).
• Enhance createInviteCode payload with new fields.
• Add: getUserDetail(userId), updateUserSubscriptionPlan(userId, plan), extendUserTrial(userId, days).

---

Phase 6: Frontend — Enhanced Invite Codes Page

Update: frontend/src/pages/admin/InviteCodesPage.tsx

Create form additions:

• Email input (optional, validated).
• Plan selector dropdown (Free / Pro / Team).
• Trial duration input (number of days, shown only when plan ≠ free).

Table additions:

• "Recipient" column (email or "—").
• "Plan" column with badge.
• "Trial" column (days or "—").
• "Email Sent" indicator.

Preserve existing create/copy/delete actions and status badges.

---

Phase 7: Frontend — User Detail Page

New file: frontend/src/pages/admin/UserDetailPage.tsx

Sections:

• Header — name, email, role badges, active status.
• Account & Subscription card — plan, status, trial end date, account display code.
• Admin Actions card — Change Role, Change Plan, Extend/Start Trial, Activate/Deactivate (modal-based).
• Recent Sessions tab — tree name, started, completed, outcome.
• Audit Logs tab — action, resource, timestamp, expandable details.
• Invite Code card — code used, plan assigned, who created it.

Update: frontend/src/router.tsx — add route admin/users/:userId.

Update: frontend/src/pages/admin/UsersPage.tsx — make user rows clickable to navigate to detail page. Ensure action menu clicks (dropdowns, buttons) don't trigger row navigation.

---

File Inventory

Files to Create

File	Phase
backend/alembic/versions/030_enhance_invite_codes.py	1
backend/app/core/email.py	2
backend/app/templates/invite_email.html	2
backend/app/schemas/subscription.py (verify doesn't exist first)	4
backend/app/schemas/user_detail.py	4
frontend/src/pages/admin/UserDetailPage.tsx	7

Files to Modify

File	Phase	What Changes
backend/app/models/invite_code.py	1	Add new columns + computed properties
backend/app/core/config.py	2	Add RESEND_API_KEY, FROM_EMAIL, email_enabled
backend/requirements.txt	2	Add resend package
backend/app/schemas/invite_code.py	3a	Add email, plan, trial fields to create/response
backend/app/api/endpoints/invite.py	3b	Accept new fields, send email, audit log
backend/app/api/endpoints/auth.py	3c	Apply invite plan/trial on registration (lines ~178–183)
backend/app/api/endpoints/admin.py	3d	Enrich user detail, add subscription endpoints
backend/app/api/deps.py	3e	Trial expiry check in get_current_active_user
frontend/src/types/admin.ts	5	Enhanced invite + new detail types
frontend/src/api/admin.ts	5	New API functions, fix invite path
frontend/src/pages/admin/InviteCodesPage.tsx	6	Form + table enhancements
frontend/src/pages/admin/UsersPage.tsx	7	Clickable rows → detail page
frontend/src/router.tsx	7	Add user detail route

Also Update (Housekeeping)

File	What Changes
CLAUDE.md	Fix invite codes endpoint reference from /invite-codes to /invites

---

API / Interface Changes

Modified Endpoints

• POST /invites — new request fields: email, assigned_plan, trial_duration_days.
• GET /invites — new response fields: email, assigned_plan, trial_duration_days, email_sent_at, has_trial, email_sent.
• GET /admin/users/{id} — enriched response with account/subscription/recent activity details.

New Endpoints

• PUT /admin/users/{id}/subscription/plan
• PUT /admin/users/{id}/subscription/extend-trial

---

Implementation Order

1. Migration 030 (invite code fields)
2. Model update (invite_code.py)
3. Resend integration (email.py, config.py, template, requirements.txt)
4. Backend schemas (invite_code, subscription, user_detail)
5. Backend API (invite.py, auth.py, admin.py, deps.py)
6. Backend tests
7. Frontend types + API client
8. Frontend invite codes page enhancement
9. Frontend user detail page
10. End-to-end testing

---

Test Plan

Backend Tests

1. Invite create with assigned_plan + trial_duration_days persists correctly.
2. Invite create with email — Resend success sets email_sent_at.
3. Invite create with email — Resend failure still returns 201, does not set email_sent_at.
4. Registration with invite applies correct subscription plan/status/period fields.
5. Registration with optional invite (REQUIRE_INVITE_CODE=false) still applies plan/trial when code provided.
6. Expired trial auto-downgrades on authenticated request.
7. Admin plan update endpoint updates subscription + creates audit log.
8. Admin extend-trial endpoint converts/extends correctly + creates audit log.
9. Enriched GET /admin/users/{id} returns expected shape and list-size caps (10 sessions, 10 audit logs).
10. Trial duration validation rejects values outside 1–90 range.
11. Free plan invite rejects trial_duration_days (consistency guard).

Frontend Verification

1. Create invite with email + plan + trial from admin UI.
2. Confirm invite table renders recipient/plan/trial/email-sent columns.
3. Open user detail from users table (click row).
4. Change plan and extend trial from detail page.
5. Confirm updated values refresh in UI.
6. cd frontend && npm run build passes.

Commands

cd backend && pytest --override-ini="addopts="
cd frontend && npm run build

---

Risks and Mitigations

Risk	Mitigation
Endpoint drift (/invite-codes vs /invites)	Update CLAUDE.md and admin API client. Verify all admin invite calls use /invites.
Subscription side-effects in auth/deps	Centralize trial-expiry logic. Cover with targeted tests.
Payload growth for user detail	Cap related arrays at 10 items, include total counts.
Email provider outages	Best-effort send with logging. Invite creation never fails due to email.
DNS not configured for Resend	Document as prerequisite. Email gracefully degrades when API key missing.
subscription.py may already exist	Verify before creating. Extend if present, create if not.
JWT session outlives trial expiry	Acceptable for beta. Document as known limitation.

---

Rollout

1. Deploy migration and backend changes.
2. Validate admin invite creation and registration path in staging.
3. Deploy frontend with new invite/user-detail UI.
4. Monitor audit logs and invite email delivery behavior post-release.

---

Assumptions

• Existing admin access control (require_admin) remains unchanged.
• Plan limits for free/pro/team are already configured in plan_limits.
• No mandatory template engine addition is required for email template rendering.
• Alembic env.py already imports InviteCode model (per LESSONS-LEARNED.md).