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

Admin Panel: Invite Codes + User Management Enhancement

Date: 2026-02-12
Status: Proposed

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/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

• Invite API path standardization: use /invites (frontend and backend aligned).
• User detail endpoint: enrich existing GET /admin/users/{id}.
• Invite email is advisory only (no strict email-match enforcement at registration).
• Invite plan/trial applies whenever a valid invite code is provided, even if REQUIRE_INVITE_CODE=false.
• Trial duration bounds: 1..90 days.
• Extend trial endpoint may convert non-trialing subscriptions to trialing.
• User detail payload includes recent summaries (latest 10 sessions + latest 10 audit logs) plus total counts.

Scope by Phase

Phase 1: Database Migration (030)

Create backend/alembic/versions/030_enhance_invite_codes.py (down revision 029).

Add 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.

Constraints:

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

Update model backend/app/models/invite_code.py:

• Add mapped columns above.
• 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

Create backend/app/core/email.py:

• EmailService.send_invite_email(to_email, code, plan, trial_days, signup_url) -> bool.
• Returns False if RESEND_API_KEY missing.
• Catches provider failures and returns False (logs warning/error).
• Never blocks invite creation.

Create backend/app/templates/invite_email.html:

• Monochrome branded HTML.
• Invite code, plan, optional trial text, signup CTA button.

Update backend/app/core/config.py:

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

Update backend/requirements.txt:

• Add resend package.

Phase 3: Backend Schemas + Endpoints

Invite code schemas

Update backend/app/schemas/invite_code.py:

• InviteCodeCreate adds:
  • email: Optional[EmailStr]
  • assigned_plan: Literal['free','pro','team'] = 'free'
  • trial_duration_days: Optional[int] (1..90)
• InviteCodeResponse adds:
  • email, assigned_plan, trial_duration_days, email_sent_at
  • computed flags has_trial, email_sent.

Invite endpoints

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

• POST /invites accepts new fields.
• Creates invite with plan/trial/email metadata.
• If email provided, attempts send:
  • on success: set email_sent_at.
  • on failure: invite still returns 201.
• Add audit log for invite creation with delivery result.
• Keep GET /invites, DELETE /invites/{code}, GET /invites/validate/{code} behavior compatible.

Registration plan assignment

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

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

Admin subscription + detail endpoints

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

• Enrich GET /admin/users/{id} response:
  • base user fields
  • account summary
  • subscription summary
  • recent sessions (10) + total count
  • recent audit logs (10) + total count
  • invite code used summary
• Add:
  • PUT /admin/users/{id}/subscription/plan
  • PUT /admin/users/{id}/subscription/extend-trial

Trial expiry check

Update backend/app/api/deps.py:

• In get_current_active_user, check account subscription.
• If status='trialing' and expired, auto-downgrade:
  • plan='free', status='active'
  • clear/normalize trial period fields
  • commit before returning user.

Phase 4: Backend Schema Additions

Use existing file backend/app/schemas/subscription.py (do not duplicate):

• Add SubscriptionPlanUpdate.
• Add ExtendTrialRequest.
• Keep/extend SubscriptionResponse as needed.

Create backend/app/schemas/user_detail.py:

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

Phase 5: Frontend Types + API Client

Update frontend/src/types/admin.ts:

• Invite response fields for email/plan/trial/email-sent metadata.
• New detail types:
  • UserDetail
  • SubscriptionDetail
  • SessionSummary
  • AuditLogSummary
  • AccountSummary.

Update frontend/src/api/admin.ts:

• Switch invite endpoints to /invites.
• Enhance createInviteCode payload.
• Add:
  • getUserDetail(userId)
  • updateUserSubscriptionPlan(userId, plan)
  • extendUserTrial(userId, days).

Phase 6: Frontend Invite Codes Page

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

• Create form fields:
  • optional email
  • plan selector (Free/Pro/Team)
  • trial days input when plan != free
• Table additions:
  • recipient
  • plan badge
  • trial column
  • email sent indicator
• Preserve existing create/copy/delete actions and status badges.

Phase 7: Frontend User Detail Page

Create frontend/src/pages/admin/UserDetailPage.tsx:

• Header: name/email/role/active.
• Account & subscription card.
• Admin actions:
  • change role
  • change plan
  • extend/start trial
  • activate/deactivate
• Tabs:
  • recent sessions
  • audit logs
• Invite code card:
  • code, assigned plan, creator.

Update frontend/src/router.tsx:

• Add route admin/users/:userId.

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

• Make rows navigate to detail.
• Ensure action menu clicks do not trigger row navigation.

API / Interface Changes

Modified

• 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.

Added

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

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.
• Resend failure still returns 201 and does not set email_sent_at.

3. Registration with invite applies correct subscription plan/status/period fields.
4. Registration with optional invite (REQUIRE_INVITE_CODE=false) still applies plan/trial.
5. Expired trial auto-downgrades on authenticated request.
6. Admin plan update endpoint updates subscription + audit logs.
7. Admin extend-trial endpoint converts/extends correctly + audit logs.
8. Enriched GET /admin/users/{id} returns expected shape and list-size caps.

Frontend verification

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

Commands

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

Risks and Mitigations

• Endpoint drift (/invite-codes vs /invites): update admin API client and validate all admin invite calls.
• Subscription side-effects in auth/deps: centralize trial-expiry logic and cover with tests.
• Payload growth for user detail: cap related arrays at 10 and include totals.
• Email provider outages: best-effort send with logging, no invite creation failure.

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 this email template rendering path.