Feature: Settings page + AI credits tracker + sidebar user drop-up

Metadata

• Issue ID: FEAT-103
• Status: Done (Phase 1 + Phase 2 landed on feature/103-settings-ai-credits-tracker, local-only at time of writing)
• Owner: danrave1234
• Related PRs: pending
• Related issues: #103, #104 (Billing page — separate), #105 (OAuth + forgot-password — separate)

Builds on FEAT-31 (cookie auth), FEAT-39 (Stripe), FEAT-33 (job queue), FEAT-40 (notifications), and the existing GCS configuration documented in credits-subscription-plan.

---

Overview

A first-class Settings surface for StudyBoost, anchored by an AI Credits Tracker at /settings/usage. Before this work the sidebar Settings button at app-sidebar.tsx:291 was a dead placeholder, /settings did not exist, and AI credit deductions were aggregate-only (one counter per cycle) with no per-event attribution.

What shipped:

• Sidebar user drop-up — replaces the three loose footer buttons (Upgrade/Manage Plan, Settings, Logout) with a single ChatGPT-style user pill that opens a popover anchored above it. Pill shows avatar, name/email, plan badge, mini credit bar; popover shows full credit bar + section links + theme toggle + log out.
• Settings shell at /settings/* with shared layout + sticky sub-nav (5 sections).
• Usage page (/settings/usage) — the headline feature. Big balance card with reset countdown, daily-credit-burn stacked bar chart, paginated activity feed with per-event metadata, category filter chips. Chart legend + filter chips are data-driven — new AI tools surface automatically with no frontend changes.
• Per-event AI credit ledger — new ai_credit_ledger table written from a unified recordAndDeductCredits() flow on BaseAiTool. Every AI tool deduction (and every dev-bypass call) writes one row with denormalized source metadata (source_label, tool_category, tokens_used, freeform metadata JSON).
• Account page — avatar upload (multipart → GCS v2/avatars/<userId>-<ts>.<ext>), profile form (first/last name, username with uniqueness check, bio, location, university), change-password form with current-password verification + strength meter.
• Notifications page — toggle preferences for 5 notification categories + 2 channels (email / in-app). Lazy-created user_notification_preferences row per user.
• Security page — placeholder UI for 2FA / Connected accounts / Active sessions (real implementation is tracked under #105 and a future security issue).
• Billing page — placeholder; real implementation is tracked under #104.
• <AuthGate> wrapper + new /unauthorized 401 page — all five settings tabs redirect signed-out users to /login?next=….
• FeatureHeader cleanup — User Capsule chip removed from the top bar; identity now lives in the sidebar drop-up only.
• Layout stability fix — added [scrollbar-gutter:stable] to the main scroller and w-full to the settings container so the sub-nav stays anchored at the same x-position across every tab regardless of content height/width.

The credit/subscription policy is in credits-subscription-plan. Auth gating follows FEAT-31.

---

Frontend Behavior

Routes

Auth gating

• frontend/components/auth/auth-gate.tsx — client component that reads useAuthUser(). While loading, renders a spinner card. Once resolved, if !user, router.replace('/login?next=<encodeURIComponent(pathname)>'). Otherwise renders children.
• frontend/app/(features)/settings/layout.tsx wraps its body in <AuthGate> so all five tabs share the same gate.

Sidebar drop-up

• frontend/components/sidebar/user-drop-up.tsx — a shadcn <Popover side="top" align="start"> whose trigger is a user pill. Trigger pill collapses to avatar-only when the sidebar is in icon mode.
• Popover contents (top → bottom):
  1. Avatar (uses profile_picture_url when set, otherwise initials from first_name / username) + name + email + plan badge.
  2. Mini credit bar (<CreditBar size="sm">) sourced from useSubscription().aiCreditsUsed / aiCreditLimit. When aiCreditLimit === null: renders "Unlimited" + sparkles icon, no bar.
  3. Five <Link> rows: Usage, Billing & Plan, Account, Notifications, Security.
  4. Inline <ThemeToggle /> from frontend/components/ui/theme-toggle.tsx.
  5. Log out — re-uses the existing LogoutConfirmModal.
• Replaces the three buttons that previously sat at app-sidebar.tsx:276–313 (desktop) and app-sidebar.tsx:403–432 (mobile drawer).
• Avatar URL resolution: relative /uploads/* paths are prefixed with backendUrl(…); absolute https:// URLs (GCS, OAuth provider) pass through unchanged.

Usage page composition

• <BalanceCard> — big headline ("X / Y credits used"), reset countdown computed from subscription.currentPeriodEnd, "Manage plan" CTA that routes through useSubscription().openBillingPortal() for paid plans or to /pricing for Free. Reserves a min-h-[220px] so the loading skeleton matches the rendered card.
• <UsageHistoryChart> — inline SVG stacked bar chart. 7d / 30d / 90d range toggle. Categories + colors derived from the actual byCategory keys in the API response, hashed against a 10-color palette so the same key always gets the same color. Three render states share the same h-44 area: skeleton (animated pulsing bars at varied heights), empty (CTA link to /ai), data.
• <ActivityFeed> — useInfiniteQuery-style cursor-paginated feed of ai_credit_ledger rows. Category filter chips populated from useUsageHistory(30) so chips track real-world tools instead of a hardcoded list. Loading state renders 6 skeleton rows inside a min-h-[480px] <ul> to reserve final page height.
• <ActivityRow> — generic, not switch-on-category. The description is built by scanning metadata for high-signal keys (gameType, difficulty, mode, stage, questionCount, cardCount, …) and surfacing up to 3 of whichever the tool happened to log. Color accent uses the same hash-to-palette mapping as the chart. Deep link: /documents/<id> for source_kind=document, /ai-courses/<id> for source_kind=course, hidden otherwise.

Account page composition

• <AvatarCard> — file picker with client-side type/size validation (JPEG/PNG/WebP/GIF ≤ 2 MB), optimistic preview via URL.createObjectURL, POST multipart/form-data to /users/me/avatar. On success calls refreshAuthUser() so the sidebar drop-up picks up the new URL.
• <ProfileForm> — controlled fields for first/last name, username, bio (500-char counter), location, university. Tracks dirty state — Save button disabled until something changes. Sends only the diff via PATCH. Email rendered read-only with a "Re-verification required (coming soon)" note. Refreshes useAuthUser() on save.
• <PasswordForm> — current/new/confirm with show/hide toggles, live strength meter (Weak/Okay/Strong via heuristic on length + character classes), inline validation for mismatch and too-short. POST /auth/change-password. Empties the form on success.

Notifications page composition

• Two card sections: Categories (product_updates, ai_completed, credit_warnings, marketing, weekly_digest) and Channels (inapp_enabled, email_enabled).
• Each row uses the local <Switch> (a minimal accessible <button role="switch"> mirroring shadcn API; not Radix — the codebase uses @base-ui/react, so we hand-rolled a tiny version).
• Optimistic toggle with rollback on failure. PATCH per-key. Loading state renders skeleton rows that match the real row's min-h-[76px] so the page doesn't grow on data arrival.

Security page composition

UI-only placeholders for issue #105 follow-on work:

• 2FA card — disabled "Set up 2FA" button, Planned chip (softer than "Coming soon"), copy explains it's on the roadmap without a firm ETA.
• Connected accounts card — Google + Apple rows, both with disabled "Connect" buttons.
• Active sessions card — current device row + disabled "Revoke all other sessions" button.

Header / sidebar layout

• frontend/components/layout/features-layout-client.tsx — <main> element uses [scrollbar-gutter:stable] so the scrollbar gutter is always reserved. Prevents horizontal shifting when content height varies between pages (Settings tabs are the most visible symptom).
• frontend/components/layout/feature-header.tsx — User Capsule chip removed. Header right-side is now just <ThemeToggle /> + <NotificationDropdown />.
• frontend/app/(features)/settings/layout.tsx — outer container uses w-full py-6 lg:py-8 max-w-7xl mx-auto. The w-full is critical: without it the container collapsed to fit-content width and mx-auto re-centered per page, drifting the sub-nav x-position by ~150 px between tabs (Playwright-verified before / after).

Loading / empty / error states

---

Backend Behavior

Module / file changes

backend/prisma/migrations/
├── 202605170900_add_ai_credit_ledger/migration.sql           ← Phase 1
└── 202605171000_add_user_settings_phase2/migration.sql       ← Phase 2

backend/src/ai/
├── base-ai-tool.ts                                           ← refactored to require buildLedgerEntry
├── ledger-entry.input.ts                                     ← new
└── tools/**.tool.ts                                          ← 11 tools updated

backend/src/subscriptions/
├── dto/list-ledger.dto.ts                                    ← new
├── dto/usage-history.dto.ts                                  ← new
├── subscriptions.controller.ts                               ← +2 endpoints
└── subscriptions.service.ts                                  ← +recordAndDeductCredits, +listLedger, +getUsageHistory, +ensureUsageTx

backend/src/storage/
├── gcs-storage.service.ts                                    ← new — uploadAvatar to v2/avatars/
└── storage.module.ts                                         ← new (@Global)

backend/src/users/
├── dto/update-profile.dto.ts                                 ← new
├── dto/update-notification-preferences.dto.ts                ← new
├── users.controller.ts                                       ← +4 endpoints (profile, avatar, get prefs, patch prefs)
└── users.service.ts                                          ← +updateProfile, +updateProfilePictureUrl, +get/updateNotificationPreferences

backend/src/auth/
├── dto/change-password.dto.ts                                ← new
├── auth.controller.ts                                        ← +POST /auth/change-password
├── auth.service.ts                                           ← +changePassword, userProfileSelect now includes profile_picture_url/bio/location/university
└── auth.types.ts                                             ← AuthUserProfile extended

backend/src/job-queue/processors/
└── course-generation.processor.ts                            ← deductCredit wrapped with recordAndDeductCredits (per stage)

backend/src/app.module.ts                                     ← +StorageModule

Data model — Phase 1 (ai_credit_ledger)

CREATE TABLE ai_credit_ledger (
  id            UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id       UUID         NOT NULL REFERENCES users(user_id)         ON DELETE NO ACTION,
  usage_id      UUID         NULL     REFERENCES subscription_usages(id) ON DELETE SET NULL,
  tool_id       VARCHAR(64)  NOT NULL,
  tool_category VARCHAR(32)  NOT NULL,
  credits       INT          NOT NULL DEFAULT 1,
  tokens_used   INT          NULL,
  model_used    VARCHAR(128) NULL,
  source_kind   VARCHAR(32)  NULL,
  source_id     UUID         NULL,
  source_label  VARCHAR(255) NULL,
  result_kind   VARCHAR(32)  NULL,
  result_id     UUID         NULL,
  metadata      JSONB        NULL DEFAULT '{}'::jsonb,
  occurred_at   TIMESTAMP    NOT NULL DEFAULT now()
);

CREATE INDEX idx_ai_credit_ledger_user_occurred  ON ai_credit_ledger (user_id, occurred_at DESC);
CREATE INDEX idx_ai_credit_ledger_user_category  ON ai_credit_ledger (user_id, tool_category, occurred_at);
CREATE INDEX idx_ai_credit_ledger_usage          ON ai_credit_ledger (usage_id);

source_label is denormalized so deleted-source rows still render. source_id is intentionally polymorphic — no hard FK because it points at different tables (documents, generated_courses, game sessions). The frontend hides the deep link when source_id IS NULL or when source_kind === 'scope'.

subscription_usages.ai_credits_used remains the source of truth for the per-cycle limit check; the ledger is for attribution only.

Data model — Phase 2 (user_notification_preferences)

CREATE TABLE user_notification_preferences (
  user_id         UUID      PRIMARY KEY REFERENCES users(user_id) ON DELETE CASCADE,
  product_updates BOOLEAN   NOT NULL DEFAULT TRUE,
  ai_completed    BOOLEAN   NOT NULL DEFAULT TRUE,
  credit_warnings BOOLEAN   NOT NULL DEFAULT TRUE,
  marketing       BOOLEAN   NOT NULL DEFAULT FALSE,
  weekly_digest   BOOLEAN   NOT NULL DEFAULT FALSE,
  email_enabled   BOOLEAN   NOT NULL DEFAULT TRUE,
  inapp_enabled   BOOLEAN   NOT NULL DEFAULT TRUE,
  updated_at      TIMESTAMP NOT NULL DEFAULT now()
);

Defaults bias toward product-relevant categories (opt-in) and away from marketing (opt-out). Row is lazy-created on first GET so the frontend always has something to PATCH.

BaseAiTool refactor

Old flow:

async run(userId, dto) {
  const result = await this.execute(userId, dto);
  if (!isBypass) await this.subscriptions.useAiCredit(userId).catch(warn);
  return result;
}

New flow:

protected abstract buildLedgerEntry(userId, dto, result): LedgerEntryInput;

async run(userId, dto) {
  const result = await this.execute(userId, dto);
  const isBypass = /* DEV_BYPASS_SUBSCRIPTION matches truthy values */;
  const entry = await this.buildLedgerEntry(userId, dto, result);
  const amount = isBypass ? 0 : (entry.credits ?? 1);
  try {
    await this.subscriptions.recordAndDeductCredits(userId, amount, entry);
  } catch (err) {
    if (err instanceof BadRequestException) throw err;   // limit-exceeded propagates
    this.logger.warn(...);                                // any other failure is warn-only
  }
  return result;
}

The limit-exceeded path now propagates (was silently swallowed before this refactor). The dev-bypass path still writes a credits=0 row so the Usage view is testable without burning real credits.

Every existing tool implements buildLedgerEntry:

The AI course-generation processor (backend/src/job-queue/processors/course-generation.processor.ts) is not a BaseAiTool — it has its own pipeline. The existing deductCredit(userId, step, courseId) helper now wraps subscriptions.recordAndDeductCredits per stage with metadata.stage (outline / module_lessons / module_exam / final_exam / mastery_analysis), so a single course generation writes 5+ ledger rows attributed to the same source_id (course UUID).

SubscriptionsService.recordAndDeductCredits

Single prisma.$transaction:

1. Look up the active Stripe-linked subscription for the user.
2. ensureUsageTx(tx, userId, planSlug) — find or create the current-cycle subscription_usages row.
3. If amount > 0: atomic conditional UPDATE subscription_usages SET ai_credits_used = ai_credits_used + $amount WHERE id = $usage AND (ai_credit_limit IS NULL OR ai_credits_used + $amount <= ai_credit_limit). If rows_affected = 0, throw BadRequestException('AI credit limit reached for current billing cycle') — the whole transaction rolls back, no ledger row is written.
4. Insert ai_credit_ledger row with the entry's denormalized fields + usage_id foreign key.

New endpoints

All routes (except /users/me/avatar's multipart handling) use the existing CookieAuthGuard. /auth/change-password re-uses the global AuthThrottlerGuard from FEAT-31 to rate-limit.

/auth/me extension

userProfileSelect in auth.service.ts now includes profile_picture_url, bio, location, university. AuthUserProfile in auth.types.ts extended to match. The frontend AuthUser type in hooks/use-auth-user.ts mirrors this. refreshAuthUser() is called after avatar upload + profile save so the sidebar drop-up renders the new picture immediately.

GCS storage

GcsStorageService reads GCP_PROJECT_ID, GCP_BUCKET_NAME, GCP_CREDENTIALS_JSON from env (the credentials JSON accepts either raw JSON or base64-encoded JSON so escaping doesn't bite). Logs a warning at startup if any of the three is missing and refuses uploads with InternalServerErrorException('Avatar storage is not configured on the server.') until they're set — the rest of the app boots fine without it.

Object path: v2/avatars/<userId>-<timestamp>.<ext>. Public URL: https://storage.googleapis.com/<bucket>/<path> (assumes public-read at the bucket level — switch publicUrlFor to V4 signed URLs if you move to uniform bucket-level access without public read). Previous avatars under the v2/ prefix are best-effort deleted to avoid orphaned objects.

Failure modes

• DB transaction rollback on limit-exceeded: ledger row is NOT inserted; BadRequestException propagates to the caller.
• Ledger insert hiccup (DB blip after the counter increment): BaseAiTool.run logs a warn but returns the result; the user already paid for the AI work, and the limit check itself was atomic with the counter.
• GCS upload failure: InternalServerErrorException('Failed to upload avatar') — users.profile_picture_url left unchanged.
• GCS credentials misconfigured at boot: backend boots; first avatar upload returns 500 with a clear message; logs at startup explain.
• buildLedgerEntry throws: BaseAiTool.run logs a warn, skips the ledger write + credit deduction, returns the result. (Trade-off: prefer "user got their result + no charge" over "user got their result + crash response".)

Course-generation processor wrap

course-generation.processor.ts previously called useAiCredit(userId) raw inside deductCredit(userId, step, courseId). New flow:

const course = await this.prisma.generated_courses.findUnique({
  where: { id: courseId },
  select: { title: true },
}).catch(() => null);

await this.subscriptions.recordAndDeductCredits(userId, 1, {
  toolId: 'ai-course-generation',
  toolCategory: 'course',
  sourceKind: 'course',
  sourceId: courseId,
  sourceLabel: course?.title ?? undefined,
  resultKind: 'generated_course',
  resultId: courseId,
  metadata: { stage: step },
});

So a 3-module × 3-lesson course generation now writes ~5 ledger rows — outline / module_lessons / module_exam / final_exam / mastery_analysis — all under the same source_id (course id), distinguishable by metadata.stage. The Usage activity row's describe() surfaces Stage: outline etc. directly from this metadata without any code change in the frontend.

---

QA Test Scenarios

---

Edge Cases

• aiCreditLimit = null (Plus / enterprise) — never divides by zero. <CreditBar> renders "Unlimited" text + sparkles icon, no progress bar. Balance card headline shows "Unlimited" instead of X / Y used.
• Subscription in past_due — Usage page stays accessible (read-only). No banner is added by this issue (that's tracked under the billing issue #104). Existing requiresPaymentAction flag is exposed by useSubscription for future work.
• Period boundary — subscription.currentPeriodEnd is the Stripe-authoritative date; the existing webhook handler (FEAT-39) resets subscription_usages.ai_credits_used on invoice.payment_succeeded. No changes here.
• Race between credit deduction and cached subscription read — <BalanceCard> attaches a window.focus listener that calls useSubscription().refreshSubscription(), so tab-switching back from /ai after burning a credit immediately re-renders the new total.
• Multi-stage course generation — each stage writes its own ledger row. The Usage activity feed lists them chronologically; a future polish could group them by source_id (course id) with a "View N stages" disclosure, but that's a follow-up.
• Refunds / credit grants — admin-side adjustments should be writable as negative ledger rows with tool_id='admin-adjustment', tool_category='other', metadata.reason. The schema allows this; no admin UI in this issue.
• Source resource deleted after ledger entry written — feed renders the row using the snapshotted source_label; the deep-link button is hidden when source_id IS NULL OR source_kind='scope'. No 404 for the user.
• Backfill — pre-existing credit usage from before this migration has no ledger rows. The Usage feed shows only post-migration activity; the existing aggregate counter is the source of truth for the headline number. No historical backfill is performed.
• Username collision — updateProfile runs a findFirst({ username, NOT: { user_id } }) precheck; collisions return BadRequestException('Username is already taken').
• OAuth-only user changing password — change-password route currently rejects with BadRequestException('No password set for this account…'). Set-initial-password support for OAuth users is tracked under #105.
• Notification preference race (user toggles twice fast) — frontend tracks saving per key and uses optimistic state with rollback. The two PATCHes both run; the last one wins.
• Avatar upload race (user picks file B before A finishes) — second upload overrides the first. The previous-URL cleanup runs against existing.profile_picture_url at the moment of upload, so A's object will be cleaned up by B's upload.
• GCS public-read assumption — publicUrlFor() returns https://storage.googleapis.com/<bucket>/<path>. If the bucket switches to uniform bucket-level access without allUsers: roles/storage.objectViewer, swap to V4 signed URLs (single-line change in GcsStorageService.publicUrlFor).
• Scrollbar gutter on Windows + Firefox — [scrollbar-gutter:stable] is supported in Chrome 94+, Firefox 97+, Safari 16+. Falls back to standard scrollbar behavior on older browsers; the sub-nav x-shift would return for users on those, but the in-app browser audit shows everyone is on modern versions.

---

Notes

Feature flags

No new feature flags for this issue.

Dependencies

• FEAT-31 (secure-cookie auth + sessions) — useAuthUser, CookieAuthGuard, AuthThrottlerGuard all consumed as-is.
• FEAT-33 (job queue) — course-generation.processor.ts reuses the queue; this issue only wraps its useAiCredit call.
• FEAT-39 (Stripe billing) — useSubscription(), getMySubscriptionView, subscription_usages table all reused. The webhook handlers that reset the cycle counter are untouched.
• FEAT-40 (notifications) — preference flags are persisted but not yet wired into NotificationsService.enqueueForUser() for gating; that's per-callsite work that happens as each notification type ships.
• credits-subscription-plan — tier limits / token-to-credit ratio.

Known limitations

• Account deletion is not implemented. The "Delete account" zone is not yet built — tracked as a follow-up.
• Email change with re-verification is not implemented. Email field on /settings/account is read-only.
• Notification preferences are not yet enforced at the dispatcher level. Toggling "Marketing" off saves the preference but doesn't yet stop marketing emails from being sent — that gating gets added as each notification site is touched. The schema and endpoints are ready.
• Activity feed CSV export mentioned in the original spec is deferred.
• 2FA, OAuth account linking, active sessions inventory are placeholders only — tracked under #105 and follow-on security work.
• GCS public-read is assumed. If the bucket later uses uniform bucket-level access without public read, swap GcsStorageService.publicUrlFor to V4 signed URLs (one-line change).
• Avatar storage costs — local-disk was the original Phase 1 implementation; Phase 2 swapped to GCS. The local-disk static-asset mount in main.ts was removed but the backend/uploads/ directory remains in .gitignore for safety.

Migration order

202605170900_add_ai_credit_ledger must run before any AI tool deduction is exercised (Phase 1). 202605171000_add_user_settings_phase2 must run before /settings/notifications is opened (Phase 2). Both are idempotent (use CREATE TABLE IF NOT EXISTS).