Support Center – Customer Management Technical Spec

Overview and Objectives

The Support Center is a comprehensive internal tool designed for admin and support teams to efficiently manage customer accounts, subscriptions, payments, and activity records. The tool provides a centralized interface for monitoring both individual users and organizations, surfacing critical details about subscription status, billing history, trial eligibility, memberships, and product engagement. The Support Center streamlines operational workflows, enhances customer support, and allows for rapid troubleshooting by linking seamlessly into key external systems (Stripe for billing, Clerk for authentication and org management).

Objectives

Provide a single dashboard for admins/support to access detailed customer information
Enable fast lookups by user or organization and detailed drill-downs
Surface all subscription, payment, trial, and usage data in one place
Facilitate direct handoffs to external systems (Stripe, Clerk) for advanced troubleshooting or account actions
Reduce support response times, improve billing transparency, and strengthen compliance

Main Use Cases

Admin views detailed user profiles, their subscription/payment status, usage, and memberships
Admin monitors organization accounts including seat usage, payments, and members
Support staff investigates user or org issues and launches into Stripe or Clerk for escalations
Staff answers customer questions about payment status, trial periods, org membership, or product usage quickly and confidently

Feature Breakdown and User Stories

By User View

Search or filter users by name, email, or Clerk ID
View list of users with at-a-glance subscription, payment, org membership, and activity status
Drill into a user for a complete detail pane with:
- Profile information and links to Clerk profile
- Current subscription(s), status, tier, and trial details
- Latest payment and invoice
- List of organizations the user belongs to, and their roles
- Number of available/used invites or org memberships
- Recent chat threads, documents, and projects created/edited

By Organization View

Search or filter organizations by name or Clerk ID
View list of organizations with summary info (plan, seat usage, payment status)
Drill into an organization for a detailed view with:
- Organization profile and links to Clerk org and Stripe customer
- Current subscriptions, status, and trial periods
- Invoice/payment history and latest transaction
- Member roster, roles, invites used/available (show seats used/total)
- Summary of active threads, documents, and product usage metrics

User Stories

As a support agent, I need to view all users and search for a specific customer by name or email so that I can provide personalized support.
As an admin, I want to see an overview of each user’s current subscription and payment status, including trial eligibility, so I can answer billing inquiries.
As support, I want to drill down into a user’s activity (chats, projects) to diagnose usage or support issues.
As a billing specialist, I need to see a full organization’s member list, seat count, subscription status, and payment history to address upgrade or overage questions.
As an admin, I need one-click access to external systems like Stripe and Clerk for handling sensitive transactions or account changes.

Front-End Requirements

General Interface

Clear navigation to switch between By User and By Organization views
Search bar and filters for quick lookup (supporting partial match on name, email, ID)
Paginated, sortable tables with summary rows for users and organizations
Actions (view, open in Clerk, open in Stripe) accessible directly from tables and detail panels

By User Screen

Table/List View

Columns: User Name, Email, Clerk ID, Subscription Status, Trial Status, Org Count, Last Payment Date
Actions: View Details, Open in Clerk, Open in Stripe (if stripeCustomerId exists)
Search and filter by name/email/status

User Detail Panel

Profile Section
- First/last name, email, Clerk ID, created date
- Link: open user in Clerk (new tab)
- External ID/Stripe Customer ID (with link if available)
Subscription Section
- Current subscription status (Active, Trialing, Canceled, etc.), tier/plan, relevant dates (start, next billing, end/cancelation date)
- Trial start/end and current status
- Latest invoice/payment summary (amount, status, date, downloadable PDF, with Stripe link)
- For multi-subscription: show list, highlight current/active
Membership Section
- List of organizations (name + role, invite usage/seat if available)
- Links to org details
Product Usage
- Recent threads (title, date last updated, link to full view)
- Recent documents/projects (title, date, linked to document view)
- Show counts for total threads, docs, and projects

Interactivity Design

Table rows are clickable; clicking a row opens the detail panel (side drawer or modal)
Clear “Open in Clerk” and “Open in Stripe” actions (open in new tab)
Visually highlight missing, expired, or failed subscription/payment states
Readable status indicators (using colored badges/icons: green=active, yellow=trial, red=canceled/failed)
Graceful display for null/missing data (e.g., “N/A,” “No subscription,” “Not a member”)

By Organization Screen

Table/List View

Columns: Organization Name, Clerk ID, Stripe Customer ID, Plan, Subscription Status, Seats Used/Total, Last Payment Date
Actions: View Details, Open in Clerk Org, Open in Stripe Customer

Organization Detail Panel

Profile Section
- Name, Clerk ID, Stripe Customer ID, created date
- Links to open org in Clerk and customer in Stripe (new tab)
Subscription & Billing
- All current/previous subscriptions, plan, term (start/end), status, trial status
- Subscription/invoice history; latest payment details (amount, status, date, PDF, Stripe link)
- Hierarchical display for multiple/archived subscriptions
Members & Seat Usage
- Total members, seats used, seats available (calculated based on plan/allowed seats)
- Roster table: name, email, role, user status, invite sent/accepted
- Warnings for over-filled seats or invite overage
Product Usage
- Threads: count, recent activity (last 5)
- Documents/projects: count, recent titles (last 5)

Interactivity and UI Guidance

Organization rows expand to detail panels as above
Action buttons for key external links should be visually distinct
Seat/invite status clearly colored (e.g., red if overfilled)
Show alert banners for unresolved problems (e.g., overdue invoice, canceled subscription)

Back-End Data Requirements and API Design

Data Retrieval & API Endpoints

User Data

GET /support/users
- Params: filter, search (name/email/ID), sort, pagination
- Returns: user summary list with org count, current sub/trial info
GET /support/users/:userId
- Returns: full user profile; current and past subscriptions; latest invoice; org memberships; recent threads (with docs/projects)
GET /support/users/:userId/activity
- Returns: last N threads, documents, projects

Organization Data

GET /support/organizations
- Params: filter, search (name/ID), sort, pagination
- Returns: org summary list with seat status, plan, subscription/payment info
GET /support/organizations/:orgId
- Returns: org profile, subscriptions, seat/membership roster, latest and past invoices, recent product usage

Sample Prisma Queries

Fetching User Summary

Find user with current subscription, latest invoice, org memberships, and activity:

prisma.user.findUnique({ where: { id }, include: { userProfile: true, subscriptions: { orderBy: { createdAt: 'desc' }, include: { invoices: { orderBy: { createdAt: 'desc' }, take: 1 } } }, organizations: { include: { organization: true } }, threads: { orderBy: { updatedAt: 'desc' }, take: 5, include: { documents: true } } } })

Fetching Organization Roster and Usage

prisma.organization.findUnique({ where: { id }, include: { subscriptions: { orderBy: { createdAt: 'desc' }, include: { invoices: { orderBy: { createdAt: 'desc' }, take: 1 } } }, members: { where: { isDeleted: false }, include: { user: true } }, threads: { orderBy: { updatedAt: 'desc' }, take: 5, include: { documents: true } } } })

Data Relationships to Surface

On user: link to current orgs, subscriptions, and recent activity
On org: link to members, seat usage, and all payments and invoices
Handle missing or deleted records gracefully; fallback to show as "No subscription" or equivalent
Always retrieve primary keys needed for external URLs (stripeCustomerId, clerkId) if exists

Edge Cases to Handle

Users with no organizations, or no subscriptions (display “None”)
Subscriptions with missing or unpaid invoices (display as warning)
Canceled or lapsed subscriptions (show status, do not allow certain actions)
Overfilled seat members (alert banner if members > plan seats)
Deleted users/memberships (hide from main view but accessible via filter if needed)

Integration with External Systems (Stripe, Clerk, etc.)

Clerk

Use stored clerkId from User/Organization for linking
When changes to user/org happen externally, run periodic sync to pull updates and refresh local data

Stripe

Use stored IDs from Subscription, Organization, Invoice, and User models
Detect webhooks from Stripe for subscription/invoice updates; update local state to match real-time changes

Integration Notes

All external links open in a new tab for operational safety
Tooltips or badges to indicate when external IDs are missing or invalid
Run scheduled jobs or webhooks to keep subscription and payment data fresh

Security and Authorization

Permissions

Only authenticated support/admin users can access the Support Center
All API endpoints require admin session/JWT; no public endpoint access
Visible data should match the admin’s role (e.g., only billing data to billing admins if roles are granular)

Data Handling

Mask emails, customer data in UI where not essential to workflow
Redact PII for users/orgs marked as deleted or removed
Do not surface payment method data, only subscription/invoice summaries
All external system links require users to have pre-existing access (e.g., rights to Clerk/Stripe dashboards)

API & System Security

Rate-limit API endpoints to prevent abuse
Audit trails for all actions taken via the Support Center (who viewed, what was accessed)
Secure sensitive fields in transport (HTTPS/TLS enforced)

Testing and Edge Cases

Test Scenarios

[Happy Path] View any user/organization with active subscription, normal seat usage, normal activity
[Edge] User with no organizations, no subscription
[Edge] User on trial, no payment yet, trial just ended
[Edge] Organization with filled/overfilled seats, seat overruns
[Edge] Subscription canceled or in a past-due/failed state (red alerts)
[Edge] User or org with null/invalid external IDs (hide or mark action links as disabled)
[Edge] Missing or unpaid invoices (show warning, no download link)
[Edge] Deleted users/memberships – hidden unless filtered for, marked “Deleted” if displayed
[Edge] API or network failures – display clear error banners and fallback UIs

Null/Missing Data Handling

For each field, if missing/null, display “N/A” or informative placeholder
Do not block display of the rest of the panel if one section fails to load

Failure States

On backend or external integration errors, display context banners in the UI (“Unable to fetch Stripe data. Retry”)
Log all exceptions for future troubleshooting

Appendix: Sample Data Structures and URIs

User Summary Response

Organization Summary Response

Sample External Links Construction