Reader Management System

1. Simple Feature Overview

The Reader Management System is the central hub for managing everyone who reads content on Hyphen. It covers the complete reader lifecycle — from the moment a person signs up, through their subscription journey, all the way to account deletion if they choose to leave.

This guide is the admin-side reference: how operators and customer-success teams run the reader directory, build and price subscription plans, define entitlements, grant complimentary access, send payment links, fulfil print, and manage institutional and bulk subscriptions. The reader's own self-service journey (browsing plans, the three-step checkout, gifting, upgrade/downgrade with proration, cancellation, and renewal) is documented end-to-end in the dedicated Subscriptions guide — this guide cross-links to it rather than duplicating it.

What You Can Do

How the Reader Journey Works

Reader visits Reader Portal
    ↓
Signs up with email/OTP, Google, or Facebook → Free account created
    ↓
Optionally subscribes to a plan → Becomes a Subscriber
    ↓
Reads content, saves bookmarks, comments on articles
    ↓
Admin monitors engagement, handles support, manages subscriptions
    ↓
Reader manages their own account, preferences, and sessions
    ↓
If needed: GDPR export, account deletion, or anonymization

2. Who Should Use This Feature

3. Before You Begin

Prerequisites Checklist

Important: Subscription plans must be created before you can assign subscriptions to readers. Payment gateways must be configured before readers can purchase subscriptions on their own. Email/SMTP must work before OTP login, password resets, and notifications will function.

Dependencies Between Modules

4. Key Terms in Simple Language

How It Works (Behind the Scenes)

Every admin action in this guide follows the same path: an Admin Console screen calls an admin API route, the route validates input and your RBAC permissions, writes to PostgreSQL (via Prisma), and the change becomes visible to the reader on the Reader Portal — usually through resolved entitlements that gate content access.

Which tables hold what:

Key admin API routes (all under the Admin Console, all RBAC-guarded):

Concepts: Plans, Entitlements & Institutional Access

A subscription plan is the unit of sale. What a plan actually unlocks is its set of entitlements, and those come in two shapes:

• Boolean entitlements — on/off access rights: includes print, archive access, can gift. Resolved from plan.features.entitlements.*.
• Numeric entitlements (limits) — quotas: max devices, archive issue limit, premium articles per month. Resolved from plan.features.limits.*.

Important architecture note: entitlements are not individual database columns. Everything is read from the plan's features JSON through parsePlanFeatures() / resolveEntitlements(). The planType enum (DIGITAL_ONLY / PRINT_DIGITAL / PRINT_ONLY) is only a UI grouping label — never treat it as a substitute for entitlements.includesPrint.

A plan also carries three catalog dimensions that decide where it appears and how the admin/reader flows adapt to it:

• Audience — INDIVIDUAL or INSTITUTIONAL. Institutional plans are filtered out of every individual flow (grant dialog, change-plan, payment links, public catalog).
• Delivery format — DIGITAL, PRINT, or BUNDLE. Drives whether the grant/checkout asks for a billing interval, an issues window, or both.
• Supported billing intervals — MONTHLY / ANNUAL whitelist. Empty = both allowed.

How institutional / bulk access differs from individual:

• Institutional — an organization buys N seats on a plan (Institution row). Readers are invited (InstitutionUser); on activation Reader.institutionId is set and the reader inherits the institution's plan. Their individual subscription card is locked — Grant/Extend/Cancel/Change-plan are replaced by a "Managed via Institutional Subscription" banner, and self-cancel/plan-change are blocked server-side. Managed from Sales → Institutions.
• Bulk — a single BulkSubscriptionRequest captures a negotiated multi-seat order. On Process, the request fans out into individual Subscription rows (type BULK), one per recipient email, with skipped/errored reporting.

Configuration Reference

Every configurable surface in Reader Management, with type, whether it is mandatory, its default, where it lives, and the role required to change it. (Roles use the RBAC permission keys from §5.17; "Admin" = full admin role.)

Subscription plan fields (Plan Editor — Readers → Subscriptions → Add/Edit Plan)

Reader directory filters (Readers → Directory)

Grant / payment-link fields

Institutional / bulk fields

Moderation actions & payment-link / fulfilment

Dependencies & Impact

Reader Management sits at the centre of the platform — almost every other module either feeds it or reads from it.

Configuration impact, at a glance:

• Changing a plan's entitlements affects every current subscriber on that plan the next time the paywall resolves access — there is no per-reader override.
• Marking a plan inactive or setting Valid Until in the past hides it from new sales but grandfathers existing subscribers.
• Setting Reader.institutionId (via an institution invite) locks the individual subscription card and blocks self-service.
• Editing the magazine schedule after subscriptions exist requires Regenerate Entitlements to propagate — it does not auto-backfill.

5. Step-by-Step Setup Guide

5.1 Reader Registration and Login Flows

Readers create their accounts on the Reader Portal (not the Admin Console). There are several ways to sign up and log in.

How a Reader Registers (Reader Portal)

1. The reader visits the Reader Portal and clicks "Don't have an account?" (or navigates to /register).
2. They see the "Create your account" page with these benefits listed:
   • Save articles to your bookmarks
   • Comment on articles
   • Weekly newsletter with top picks
   • Access to free content library
3. They fill in:
   • Full name (optional)
   • Email address (required)
   • Subscribe to our weekly newsletter checkbox (checked by default)
   • I agree to the Terms of Service and Privacy Policy checkbox (required)
4. They click "Create Account".
5. A 6-digit OTP is sent to their email.
6. They enter the OTP on the verification screen and click "Verify & Sign In".
7. Their account is created and they are logged in.

Alternative — Social Sign-Up:

• The reader can click "Sign up with Google" or "Sign up with Facebook" instead.
• They must accept the Terms of Service checkbox before social sign-up buttons become active.
• A message appears: "Please accept the terms above to use social sign-up" if they try to click before accepting.

How a Reader Logs In (Reader Portal)

1. The reader visits the Reader Portal and navigates to /login.
2. They see the "Welcome back" page.
3. They enter their email address and click "Send OTP".
4. A 6-digit OTP is sent to their email.
5. They enter the code and click "Verify & Sign In".
6. They are logged in.

Alternative — Social Login:

• Click "Sign in with Google" or "Sign in with Facebook".

Alternative — Password Login:

• If the reader has set a password (e.g., through password reset), they can use email + password to log in.

Forgot Password Flow

1. From the login page, the reader clicks "Forgot your password?".
2. They enter their email address and click "Send Reset Link".
3. They see: "If an account exists for [email], you'll receive a password reset link shortly."
4. They check their email for the reset link.
5. They click the link, which takes them to the "Reset your password" page.
6. They enter a new password that meets the requirements:
   • At least 8 characters
   • Contains a letter
   • Contains a number
7. They confirm the password and click "Reset Password".
8. They see a success message and can click "Sign in" to log in with their new password.

Tip: The reset link expires after a set period. If the reader's link has expired, they'll see an "Invalid Reset Link" message and can request a new one.

5.2 Reader Directory and Profile Management in Admin Console

1

2

3

1Reader Growth — new registrations and active reader trends

2Subscription Health — active vs expired subscriptions

3Engagement metrics — reading activity and session data

The Reader Directory is where admin users browse and manage all registered readers.

Accessing the Reader Directory

1. Log in to the Admin Console.
2. Click "Readers" in the sidebar.
3. You'll see the Readers Overview dashboard with key metrics:
   • Reader Growth: Total Readers, New This Week, New This Month, Growth Rate
   • Subscription Health: Active Subscribers, Churn Rate, Trial Conversions, Avg Subscription Value
   • Engagement: Active Today, Avg Session Duration, Articles Read Today, Comments Today
   • Moderation Snapshot: Pending Comments, Flagged Items, Open Reports, Banned Users
4. Click "Reader Directory" (or navigate to Readers → Directory).

Browsing and Filtering Readers

On the Reader Directory page, you'll see:

• Stats Cards at the top: Total Readers, Subscribers, Institutional Users, New This Month
• Search bar — search by name or email
• Filter dropdowns:
  • Status: All Status, Active, Inactive, Banned, Pending Verification
  • Tier: All Tiers, Free, Registered, Subscriber, Institutional
  • Subscription Status: All, Active, Cancelled, Expired, Past Due, Trial, Complimentary
• Clear Filters button to reset all filters

The reader list shows a table with columns:

• Name — the reader's display name
• Email — their email address
• Tier — their access level (Free, Registered, Subscriber, Institutional)
• Status — their account status (Active, Inactive, Banned, Pending Verification)
• Joined Date — when they registered
• Last Login — when they last logged in
• Actions — View (→), Ban, Delete

Viewing a Reader's Profile

1. In the Reader Directory, click the View (→) button on any reader row.
2. You'll see the Reader Details page with breadcrumbs: Readers → Directory → [Reader Name].

The page includes:

User Summary Card (always visible at top):

• Avatar with initials
• Status badge (Active / Inactive / Banned / Pending Verification)
• Tier badge (Free / Registered / Subscriber / Institutional / Admin)
• Trusted badge (if applicable)
• Edit Profile button
• Quick stats: Member since, Last login, Total logins, Comments

Action Buttons (top right):

• Refresh — reload reader data
• Grant Subscription — appears if the reader has no active subscription and is not institutional
• Reset Password — sends a password reset email to the reader
• Ban Reader / Unban — depending on current status

Profile Information Card:

• Bio, Location, Website, Joined date, Last login, Total logins, Comment count

Subscription Card:

• Plan name, Status badge (Active / Past Due / Cancelled / Complimentary)
• Start date, Renewal/End date, Payment method
• Actions: Extend subscription, Cancel subscription

Institutional Subscription (if applicable):

• Institution name, Access dates, Seat count

Devices List:

• Each device shows: Device name, Last seen date, Revoke button

GDPR Actions:

• Export Data — downloads all reader data as a JSON file
• Anonymize — permanently removes all personal information (requires confirmation)

Editing a Reader's Profile

1. On the Reader Details page, click "Edit Profile" in the User Summary Card.
2. Edit the reader's name and email inline.
3. Save your changes.

Note: You cannot change a reader's password directly. Use the "Reset Password" button to send them a reset link.

Exporting the Reader Directory

1. On the Reader Directory page, click the Export button (download icon) in the top right.
2. A file containing the filtered reader list will download.
3. This requires the USERS_EXPORT permission.

5.3 Create and Manage Subscription Plans

Subscription plans define what readers get when they subscribe. You must create at least one plan before readers can subscribe.

Viewing Existing Plans

1. Navigate to Readers → Subscriptions in the Admin Console sidebar.
2. You'll see the Individual Subscriptions page with:
   • Key Metrics: Active Subscribers, New This Month, Churned This Month, Monthly Revenue
   • Revenue Metrics: Annual Recurring Revenue, Avg Revenue Per User, Trial Conversions, Conversion Rate
   • Subscription Plans section showing all plans in a card grid

Each plan card shows:

• Plan name and display name
• Plan type (Digital Only / Print+Digital)
• Price (monthly and/or annual)
• Features list
• Subscriber count
• Edit and Delete buttons
• Active/Inactive toggle

Creating a New Plan

1. Click the "Add Plan" button (+ icon) in the top right.
2. A slide-out panel appears: the Plan Editor.
3. Fill in the following sections:

Basic Info:

Catalog Dimensions — three fields that decide where the plan appears and how reader/admin flows adapt to it:

These dimensions are backfilled for existing plans (institutional via the Institution → plan relation; Print/Bundle via the includes print entitlement; intervals from existing monthly/annual prices) by migration 20260530000006.

Pricing:

Features & Entitlements:

Options:

Print Fulfilment & Inventory (only renders when Plan Type = PRINT_DIGITAL):

What "current-issue inventory check" does at checkout — when a reader picks a Print plan, the checkout calls a public endpoint that asks Shopify "is the current-issue product in stock?" The result decides whether the Current Issue radio is offered, disabled, or hidden, per the behaviour above. If the Shopify call fails the checkout will not silently grant Current Issue — the reader sees a "stock check unavailable, please retry" message and the order-time guard (server-side, runs again at Pay) will return a 503 rather than risk an over-promise.

Integration:

4. Click "Save" to create the plan.

Editing an Existing Plan

1. On the Subscriptions page, find the plan card and click "Edit".
2. The Plan Editor opens with the current values pre-filled.
3. Make your changes and click "Save".

Activating or Deactivating a Plan

• Use the Active/Inactive toggle on the plan card.
• Inactive plans are not shown on the public pricing page.
• Existing subscribers on an inactive plan are not affected.

Previewing the Pricing Page

• Click "Preview Pricing Page" in the top right to see how plans appear to readers on the Reader Portal.

5.4 Assign, Upgrade, and Cancel Subscriptions

Granting a Complimentary Subscription

Use this when you want to give a reader free access — for example, for an author, partner, VIP, or promotional access.

1. Navigate to Readers → Directory.
2. Find the reader and click View (→) to open their profile.
3. Click the "Grant Subscription" button (visible only if the reader has no active subscription and is not institutional).
4. A modal appears: "Grant Subscription" with the message "Manually assign a complimentary subscription to [Reader Name]."
5. Fill in:

Plan-aware fields: the dialog renders different fields depending on the selected plan's delivery format — Digital → Billing Interval (+ optional override); Print → Issues counter; Bundle → both. The grant is routed through /api/readers/[id]/grant-subscription, which computes the period-end from the delivery format and the chosen billing interval.

6. Click "Grant Subscription".
7. The reader's tier changes to Subscriber and their subscription status shows as Complimentary. An issue-entitlement set is generated immediately for print/bundle grants, and a subscription granted email + in-app notification are sent.

Extending a Subscription

1. Open the reader's profile in Admin Console.
2. In the Subscription card, click "Extend subscription".
3. Select the extension duration.
4. An info confirm dialog shows the old → new end date; confirm to apply.

Extend is hidden (not just disabled) when the subscription is Cancelled or Expired — extending a dead subscription is never the right action. On those subscriptions, use Reactivate, Grant New Subscription, or Send Payment Link instead (they surface side by side).

Reactivate is an immediate, non-renewing admin action. The confirmation shows the exact access end time: an unexpired cancellation restores only its remaining time; an already-expired subscription receives one fresh complimentary term using the plan's configured duration. No gateway charge or automatic renewal is restarted, so the reader must renew normally after that date.

Cancelling a Subscription (Admin Side)

1. Open the reader's profile in Admin Console.
2. In the Subscription card, click "Cancel subscription".
3. A warning confirm dialog requires you to type CANCEL to proceed and to enter a free-text reason.
4. Confirm. The reason is persisted (churn reason = Admin cancel + the survey response text) for churn reporting, and a cancellation email is sent.
5. The reader keeps access until the end of their current billing period; after that their tier changes back to Free or Registered.

Sending a Payment Link (Support)

When a reader needs to pay for a plan you've quoted (or to recover a failed payment), use Send Payment Link from the subscription card:

1. Click Send Payment Link, pick the plan (Individual plans only) and billing interval.
2. The system emails a Reader Portal checkout link. A cancelled/expired reader's current plan and interval are selected by default.
3. If signed out, the reader sees the sign-in dialog and returns to the same checkout after authentication. Normal checkout verification activates the subscription after payment.
4. The action is shown only for Cancelled or Expired subscriptions. If the reader reopens the emailed URL after the target plan is active, Reader Portal redirects them to Account → Subscription instead of offering another payment.

Previously-created hosted Razorpay links retain their original tracked lifecycle and remain payable/cancellable until terminal.

How a Reader Cancels Their Own Subscription (Reader Portal)

1. The reader logs into the Reader Portal.
2. Navigates to Account → Subscription (via the sidebar).
3. Under "Manage Subscription", clicks "Cancel Subscription".
4. A confirmation dialog appears: "Are you sure you want to cancel your subscription? You will continue to have access until the end of your current billing period on [date]."
5. The reader clicks "Yes, Cancel".
6. Their subscription shows as "Cancels on [date]" until the period ends.
7. They can click "Keep Subscription" to change their mind before the period ends.

Reader-side checkout — what the reader sees

• Step 2: Subscription Details
  • For Print / Print+Digital plans, the Start your print subscription from radios show Current Issue and Next Issue.
    • The Current Issue option is automatically gated by the live Shopify stock check (see §5.3 Print Fulfilment & Inventory). When stock is zero the reader sees one of three things based on the plan's unavailable behaviour setting: a friendly message with auto-pick Next Issue, a disabled radio, or a hidden radio.
    • A "(checking stock…)" inline pill renders while the inventory check is in flight.
    • If the Shopify call fails the radio is disabled and a yellow alert appears — the reader can proceed with Next Issue.
  • The Recipient + Shipping Address sections collect a structured address: Address Line 1*, Address Line 2 (optional), Landmark / Area (optional), City*, State* (Indian-states dropdown when Country=IN), Country*, PIN Code* (6-digit if IN). Required fields enforce inline validation — print plans cannot proceed until they're complete.
  • The reader's saved profile address (if any) pre-fills these fields. A "Save this address to my profile" checkbox (default on) writes the captured address back so it's pre-filled on the next order.
• Step 3: Payment
  • The Razorpay button creates an order; the order-time guard (server-side) re-checks Shopify stock. If stock dropped to zero between page-load and click, the server downgrades the request to Next Issue and returns a printStartDowngrade flag the client surfaces in a "we updated your selection" toast.

5.4a Print Fulfilment List

The fulfilment workflow lets your operations team produce, per issue, the list of subscribers who need a print copy — and mark them as dispatched once mailed.

Where: Readers → Subscriptions → Fulfilment in the Admin Console.

Permissions required: fulfilment:read to view the list, fulfilment:manage to mark dispatched. Both are auto-granted to the Publishing Team role; admins always have them.

How the list is built

For every successful Print / Print+Digital subscription, the system writes one Issue Entitlement row per issue the subscriber is entitled to (matching the plan's durationIssues count, or counted from the magazine schedule for month/day plans). The fulfilment list is the set of those rows for the chosen issue, filtered to print plans, with revoked rows excluded.

Workflow

1. Pick the issue. The page defaults to the current published issue. Use the Issue dropdown to switch.
2. Audit addresses. A red-tinted row + inline "Incomplete — missing X, Y, Z" warning marks any subscriber whose required address fields are missing on both the subscription record AND the reader's profile fallback. Toggle Show only subscribers with incomplete addresses to triage.
3. Select rows. Use the per-row checkbox or the header Select all to pick the subscribers you've actually mailed.
4. Mark Dispatched. Click Mark Dispatched to flip fulfilmentStatus from PRINT_PENDING to PRINT_DISPATCHED. The action is audit-logged with your user, the entitlement IDs, and an optional delivery note.
5. Re-export guard. If you select a row that's already PRINT_DISPATCHED (or PRINT_DELIVERED), the action refuses with a clear message until you tick Force re-export — that flag is also audit-logged so re-exports are searchable.

Address fallback rule: the recipient's address is taken from the Subscription record's shipping fields first (what they entered at checkout). When the subscription doesn't have a value, we fall back to the Reader profile address. Both surfaces let the operator update fields if the reader emails a correction.

Generating labels for the dispatched batch

See §5.13a — the fulfilment page has a Generate Labels button that streams CSV (Excel-compatible) or printable HTML straight to the operator's browser.

5.5 Gift Subscriptions

Gift subscriptions allow one person to purchase a subscription for another person.

Managing Gift Subscriptions in Admin Console

1. Navigate to Readers → Subscriptions → Gifts (or click the gifts link on the Subscriptions page).
2. You'll see the Gift Subscriptions page with:
   • Search bar — search by buyer name, recipient email, or gift ID
   • Status filter: All Statuses, Pending Payment, Paid, Sent, Activated, Expired

Gift Subscription Lifecycle

Viewing Gift Details

1. Click the View button (eye icon) on any gift row.
2. A slide-over panel shows:
   • Status badge and Gift ID
   • Amount (highlighted card)
   • Buyer section: name and email
   • Recipient section: name, email, phone, address
   • Gift Message (if the buyer included one)
   • Plan details
   • Timeline: Created, Paid, Sent, Activated, Expires dates
   • Linked Subscription (if activated — shows reader details and period)
   • Payment Reference ID

Changing Gift Status (Admin Action)

1. In the gift detail panel, scroll to "Admin Actions".
2. Click the appropriate status button to move the gift to the next stage.
3. For example, if a gift is PAID but was not automatically sent, you can manually change it to SENT.

Important: Only plans with the "Allow Gift" option enabled can be used for gift subscriptions. Check this in the Plan Editor.

5.6 Institutional Subscriptions and Reader Access

Institutional subscriptions give organizations (universities, libraries, companies) access for multiple readers.

Institutional lock on the reader card — when a reader belongs to an institution (Reader.institutionId is set), their subscription card shows a purple "Managed via Institutional Subscription" banner in place of the Grant / Extend / Cancel / Change-plan buttons. Their access is governed by the institution's plan, so self-cancel and plan-change are blocked server-side. Manage these readers from Sales → Institutions, not from the individual subscription card. See the Sales System guide for the full B2B workflow.

Where to Manage Institutions

• Navigate to Sales → Institutions in the Admin Console sidebar.
• The old path Readers → Subscriptions → Institutional redirects here.

Creating an Institutional Subscription

1. Go to Sales → Institutions and click "Add Institution".
2. Fill in the institution details:

3. Save the institution.

Inviting Readers to an Institution

1. Open the institution's detail page.
2. Go to the Users tab.
3. Click "Add User" or "Invite" to add individual readers.
4. To invite multiple readers at once, click "Send Bulk Invitations" and enter the email addresses.
5. Each invited reader receives an email with an activation link.

How an Invited Reader Activates Their Account

1. The invited reader receives an email with an activation link.
2. They click the link and see the "Activate Your Account" page showing: "You've been invited to join Hyphen through [Institution Name]."
3. If they don't have an existing account:
   • They see their name and email (pre-filled from the invitation).
   • They create a password (minimum 8 characters, must contain a letter and a number).
   • They confirm the password and click "Create Account".
4. If they already have a Hyphen account:
   • They see: "An account already exists with this email."
   • They click "Link My Account" to connect their existing account to the institutional subscription.
5. After activation, they see: "Welcome to Hyphen! Your account has been activated. You now have full access to Hyphen through your institutional subscription."
6. They click "Sign In to Get Started".

Renewing an Institutional Subscription

1. Open the institution's detail page.
2. Click "Renew".
3. Update the end date, seats, and amount as needed.
4. Save the renewal.

5.7 Bulk Subscription Requests

Bulk subscriptions handle large orders (multiple seats) that require negotiation and manual processing.

Viewing Bulk Requests

1. Navigate to Readers → Subscriptions → Bulk (or the bulk subscriptions link).
2. You'll see the Bulk Subscription Requests page.
3. Filter by status: Pending, Negotiating, Approved, Processing, Completed, Rejected.

Bulk Request Lifecycle

Processing a Bulk Request

1. Click View on an approved request.
2. Click "Process" (only available for approved requests).
3. A processing modal appears showing:
   • Contact name and seat count
   • Plan assigned
4. In the Recipient Emails text area, paste the email addresses — one per line or comma-separated.
   • Tip: "Paste emails from your Excel file. One email per line, or comma-separated."
5. Click "Process".
6. The system shows results:
   • Created: number of subscriptions successfully created
   • Skipped: emails that already have subscriptions
   • Errored: any failures

Editing a Bulk Request

1. Click Edit on a request.
2. Update the Status, Negotiated Amount (in INR), or Notes.
3. Click "Save".

5.8 Reader Account Pages in Reader Portal

When a reader logs in to the Reader Portal and visits their account, they see a sidebar with these pages:

Account sidebar gating: the Preferences page is shown only to paid subscribers in the account sidebar. The other pages (Profile, Reading History, Bookmarks, Notifications, Subscription, Sessions, Activity) are visible to every signed-in reader.

Profile Page

The reader sees their:

• Avatar (from linked social account or initials)
• Display Name — editable, max 100 characters. Help text: "This is how your name will appear on comments and your public profile."
• Bio — editable, max 500 characters with counter
• Location — editable (e.g., "Mumbai, India")
• Website — editable URL field
• Shipping & Contact — phone number + structured address (Address Line 1, Address Line 2, Landmark, City, State, Country, PIN). All optional on the profile, but required at checkout for Print plans. Saving here means the reader's next checkout is pre-filled.
• Account Security section showing email (with Verified badge) and password status
• Danger Zone section with "Delete Account" option

Subscription Page

The reader sees:

• Current Plan card with status badge (Active / Past Due / Cancelled / Expired / Trialing / No subscription)
• Plan details: name, type (Individual / Institutional / Gift / Complimentary), billing period, cancellation status
• Print Delivery Schedule (if their plan includes print) — shows upcoming and past deliveries with status (Scheduled / Processing / Shipped / Delivered)
• Your Benefits — checkmark list of included features (e.g., "Unlimited access to all articles", "Full digital archive access")
• Manage Subscription — buttons for "Change Plan" and "Cancel Subscription"
• Payment History table with Date, Description, Amount, and Status (Paid / Pending / Failed)

If the reader has no subscription, they see: "You don't have an active subscription." with a "View Plans & Subscribe" button.

Full reader self-service journey: browsing plans, the three-step checkout, gifting, upgrade/downgrade with proration, cancellation, renewal/win-back, and the Subscription History page are documented end-to-end in the dedicated Subscriptions guide.

5.8a Reader Search Scope

The reader portal's search page (/search) spans multiple content types and merges them into the results, so a reader looking for a person or a book finds them, not just articles.

Search now covers:

Notes that affect what a reader actually sees:

• Archive issues are discovery-gated. Archived-issue cards appear in search results only for readers whose subscription grants the archive access entitlement. This is a discovery/UX gate, not a hard content lock.
• Personalization. When the reader has selected topics in Preferences, relevance-sorted results are boosted toward those topics (an "Results personalized based on your interests" note appears).
• Filters & sort (section, access level, sort by relevance/date/title) and tag-only searches (/search?tag=climate) still work as before; section and access-level filtering is applied server-side.

5.9 Bookmarks, Reading History, and Preferences

Bookmarks (Reader Portal)

• Readers save articles by clicking the bookmark icon on any article page.
• The Bookmarks page (Account → Bookmarks) shows all saved articles as a two-column card grid (the standard article card). The header shows a saved count and the hint "… you've saved for later. Click the bookmark to remove."
• Each card shows the article thumbnail, section tag, read time, title (clickable), and author — excerpts are hidden on this grid.
• To remove a bookmark, the reader clicks the bookmark icon on the card, which shows a confirmation prompt first (this guards against accidental removal).
• If no bookmarks: "No bookmarks yet. Save articles you want to read later by clicking the bookmark icon." with a "Browse Articles" button.

Reading History (Reader Portal)

• Reading history is tracked automatically when a reader opens an article.
• The Reading History page (Account → Reading History) lists recently read articles grouped by month and year (e.g., a "JUNE 2026" badge), newest group first.
• Each entry shows:
  • Article title (clickable — resumes at the saved scroll position for partially read articles)
  • Author name, and Translator as "… | Translated by …" when present (pulled from a richer history API response)
  • A relative date label (TODAY / YESTERDAY / "23 JUN")
  • A remove (trash) control that appears on hover for that entry
• A Clear All action (top-right) removes the entire history after a confirmation dialog ("Clear reading history? … This cannot be undone.").
• If no history: "No reading history yet. Start reading articles and they'll appear here." with a "Browse Articles" button.

Preferences (Reader Portal)

The Preferences page (Account → Preferences) has five sections:

1. Content Preferences:

• Reader selects topics of interest from available sections and tags.
• Selected topics are shown as highlighted pills.
• Used to personalize the "For You" feed and content notifications.
• Suggested Topics appear if the reader has reading history — shown as dashed-border pills with a "+" icon.
• Status text shows how many topics are selected.

2. Email Notifications:

3. Push Notifications:

• Browser Push Notifications toggle — "Receive instant notifications in your browser for new issues, content updates, and subscription alerts."
• Only available if the reader's browser supports push notifications.

4. Reading Preferences:

• Font Size: Small, Medium, or Large
• Theme: Light, Dark, or Sepia

5. Data Privacy:

• "Download My Data" button — downloads all reader data as a JSON file named my-hyphen-data-{DATE}.json.
• Help text: "Read our Privacy Policy to learn more about how we handle your data."

After making changes, the reader clicks "Save Preferences".

5.10 Sessions and Device Management

Reader-Side Session Management (Reader Portal)

1. The reader navigates to Account → Sessions.
2. They see a list of Active Sessions with:
   • Device icon (mobile, tablet, or desktop)
   • Device name (e.g., "Chrome on Windows")
   • "This device" badge on their current session
   • IP address and Last active timestamp
   • "Sign out" button on non-current sessions
3. To revoke a suspicious session, click "Sign out" on that session.
4. An info box explains: "Each session represents a device or browser where you are signed in. If you see a session you don't recognise, sign out of it and change your password immediately."

Admin-Side Session and Security Settings

1. Navigate to Settings → Sessions in the Admin Console.
2. Configure:

3. Click "Save" to apply changes.
4. The page shows when settings were last updated and by whom.

Revoking a Reader's Session from Admin Console

1. Open the reader's profile in Readers → Directory → [Reader].
2. Scroll to the Devices section.
3. Click "Revoke" next to the device session you want to end.
4. The reader will be logged out on that device.

5.11 Notifications and Email Preferences

How Readers Receive Notifications

Readers receive notifications through three channels:

1. In-app notifications — visible on the Notifications page in the Reader Portal
2. Email notifications — sent to their email based on their preferences
3. Push notifications — browser push notifications (if enabled)

Notification Types

Notifications Page (Reader Portal)

1. Reader navigates to Account → Notifications.
2. They see a card list with:
   • A header showing the count of unread notifications (or "All caught up")
   • "Mark all as read" button (appears when there are unread notifications)
   • "All" / "Unread" filter tabs
   • Each notification card shows: a coloured type badge (New Issue, New Content, Renewal, Subscription, Comment, System, Welcome), the title, the message, and a relative timestamp. Unread cards are tinted and carry a check button to mark that one as read.
   • Clicking a card marks it read; cards with an action URL also navigate to the linked page.
   • "Load more" button for pagination (20 per page)

Email Unsubscribe

• Every email sent to readers includes an unsubscribe link.
• Clicking the link takes them to an unsubscribe page where they can manage their email preferences.
• Readers can also manage email preferences from Account → Preferences → Email Notifications.

5.12 Payment and Subscription Checkout

How a Reader Subscribes (Reader Portal)

1. The reader visits the pricing page on the Reader Portal (linked from the subscription page or homepage).
2. They see available plans with pricing and features.
3. They select a plan and billing period (monthly/annual).
4. They are directed to the payment checkout:
   • Razorpay — for INR payments
   • Stripe — for USD/international payments
5. After successful payment, their subscription is activated immediately.
6. They can view their subscription details on Account → Subscription.

Payment History (Reader Portal)

• Readers can view their payment history on the Subscription page.
• Each entry shows: Date, Description, Amount, and Status (Paid/Succeeded, Pending, Failed).

Payment Management (Admin Console)

• Admin users can view payments through the admin payment management interface.
• Capabilities include viewing payment details, processing refunds, and tracking payment status across gateways.

Dependency: Payment gateways (Razorpay and/or Stripe) must be configured before readers can purchase subscriptions. Contact your DevOps team to set up gateway credentials.

5.12a Dummy Payment Mode (UAT)

Dummy Payment Mode is a separately-toggled gateway that lets the UAT environment exercise the full subscription journey — registration → plan select → checkout → activation → entitlement → access — without real money or real Razorpay credentials. Dummy never calls Razorpay. Every Payment row it writes is tagged gateway='dummy' and isDummy=true for unmistakable filtering.

Gating (revised 2026-05-01 post-launch hardening):

The original two-key gate combined DUMMY_PAYMENT_MODE_ENABLED with a NODE_ENV !== 'production' check, plus an ALLOW_DUMMY_IN_PROD opt-in for production. We discovered this didn't work for UAT — Next.js bakes NODE_ENV='production' into every deployed build, so the original contract never permitted Dummy on UAT.

The current contract is default ON, single-key opt-out:

Both /api/payments/dummy/create-order and /api/payments/dummy/simulate return 404 Not Found when either the env floor is off OR the DB feature flag is off. The 404 is deliberate — the URL must not reveal the gateway exists in environments where it's disabled.

What the reader sees (only when enabled):

When Dummy is on, it's the only payment option on the checkout's payment-method picker — Razorpay/Stripe tiles are hidden so an operator can't accidentally pick a broken / unconfigured live gateway. A clearly-marked yellow "Dummy Gateway (UAT only)" panel renders with two side-by-side buttons:

• Simulate Success — runs the same activation pipeline as a real Razorpay success: subscription upserted to ACTIVE, structured shipping persisted (and optionally saved to profile), per-issue entitlements generated, welcome + payment-receipt emails sent, audit-logged.
• Simulate Failure — writes a Payment row with status='FAILED' and leaves the subscription in PAUSED. The reader sees a "Dummy payment simulated as FAILED" message.

Audit trail. Dummy payments show up alongside Razorpay payments in the admin payments list, distinguishable by the dummy gateway value and the isDummy=true flag. The composite index (gateway, is_dummy) makes filtering fast.

Operational rule: Production processes should always set DUMMY_PAYMENT_MODE_ENABLED=false to disable Dummy mode. The single-key opt-out + DB flag is the safety surface; the two-key NODE_ENV gate is gone.

5.13 Magazine Schedule (Print+Digital)

The Magazine Schedule maps each calendar month to a magazine Issue. This mapping is the load-bearing input for per-issue entitlement generation — when a reader subscribes to a Print plan, the system walks the schedule from the reader's start month and writes one entitlement row per qualifying issue. Without an Issue mapped on a schedule row, no entitlement is generated for that month and the reader won't appear on the Print Fulfilment list.

Setting Up the Magazine Schedule

1. Navigate to Readers → Subscriptions → Magazine Schedule.
2. You'll see the schedule page with:
   • Year filter dropdown.
   • "Generate Year" button — creates 12 placeholder rows (Jan–Dec) for the active year in one click. Idempotent — re-running on a partial year only fills missing months.
   • "Add Entry" button — for one-off rows.
   • "Regenerate Entitlements" button — re-runs entitlement generation for every active subscription against the current mapping (use after editing the mapping; idempotent).
   • Schedule table with columns: Year, Month, Label, Mapped Issue, Active toggle, Edit action.
   • A green dot on rows that are Active and mapped to a published Issue — the only state in which entitlements are produced for new subscribers.

First-time configuration sequence (recommended)

1. Create at least one Issue with status='published' at Magazine → Issues → New Issue.
2. Click Generate Year for the active year — creates the 12 placeholder rows with auto-labels ("January 2026", "February 2026", …).
3. Click Edit on the row for the month you want subscribers entitled to (e.g. May 2026), pick the Issue from the searchable picker, and save.
4. Repeat Step 3 for any other months you want covered.
5. Subscribe a test reader via Dummy → Simulate Success and verify they appear on the Print Fulfilment list when you pick that issue.

Adding or editing a single entry

1. Add Entry opens a modal with Year / Month / Label / Mapped Issue picker / Active toggle. Saves a new row, or warns if the (year, month) slot is already in use.
2. Edit on an existing row opens the same modal pre-filled (Year and Month are locked since they're the row's identity). Use this to map an Issue, change the label, or flip Active.
3. The Issue picker is searchable by issue number, title, or status — and includes drafts, so admins can pre-map issues that haven't been published yet. The entitlement resolver only grants access once the mapped Issue's status is published, so pre-mapping is safe.

Active toggle

1. Click the Active toggle on a row.
2. A confirmation dialog appears: "Activate/Deactivate Schedule Entry" with the label and month/year.
3. Click "Confirm". The mapped Issue is preserved through the toggle (this was a bug in the previous version — toggling Active used to wipe the mapping).

Regenerate Entitlements after a schedule edit

Schedule edits don't auto-propagate to subscriptions that activated before the edit. After mapping issues, click "Regenerate Entitlements" in the Schedule page header (or on the Print Fulfilment empty-state). It walks every ACTIVE / TRIALING subscription and re-runs entitlement generation against the current mapping. Idempotent — safe to re-run.

Note: Print delivery schedule entries also appear on the reader's Subscription page in the Reader Portal under the "Print Delivery Schedule" section.

5.13a Label Templates

Label Templates configure how address labels render and export. The fulfilment list (§5.4a) uses the chosen template to produce a CSV file or a printable HTML page sized for the operator's printer.

Where: Settings → Labels in the Admin Console.

Permission required: labels:manage (auto-granted to Publishing Team and admins).

Template fields

Generating labels from the fulfilment page

1. On Readers → Subscriptions → Fulfilment, select the rows to mail.
2. Click Generate Labels.
3. The browser receives either a CSV download (Excel-compatible) or a printable HTML preview, depending on the template's Export Format.
4. For HTML output: use the browser's Print dialog (or Save as PDF) — the page's @page CSS is sized for the chosen label.
5. The export is audit-logged with the issue ID, template, total selected, exported, and skipped-for-incomplete-address counts.

Why no native PDF / Excel binary today? Direct binary export is deferred to a focused dep-add (drop in pdf-lib and exceljs — neither is currently bundled). CSV + the printable HTML preview cover every daily fulfilment workflow we have today.

5.14 Renewal Reminders, Invitation Reminders, and Automated Tasks

The platform sends automated notifications and reminders based on subscription events and system triggers.

Types of Automated Notifications

How to Check if Reminders Are Being Sent

1. Check if the reader has Renewal Reminders enabled in their email preferences:

   • Open the reader's profile in Admin Console.
   • Check their notification preferences.
   • Or ask the reader to check Account → Preferences → Email Notifications → Renewal Reminders on the Reader Portal.

2. Verify that email is configured and working:

   • Go to Settings → Email → Accounts in Admin Console.
   • Click into the account mapped to OTP / account-security and click Verify connection.
   • Confirm at Settings → Email → Purposes that otp and account_security have a primary account.

3. If notifications are not being delivered, check:

   • The reader's email preferences (they may have opted out)
   • Spam/junk folder
   • Email delivery logs
   • Whether the automated task/cron job is running (contact DevOps)

Current Status: Automated renewal and expiry notifications are implemented. The timing and frequency of these reminders depends on the cron/scheduled task configuration managed by your DevOps team.

5.15 Account Deletion, GDPR Export, and Anonymization

GDPR Data Export (Admin Console)

1. Open the reader's profile in Readers → Directory → [Reader].
2. Scroll to the GDPR Actions section.
3. Click "Export Data" (with download icon).
4. A JSON file downloads named hyphen-data-export-{readerId}.json.
5. The file includes: profile, subscriptions, bookmarks, comments, and reading history.

GDPR Data Export (Reader Self-Service)

1. Reader navigates to Account → Preferences on the Reader Portal.
2. Scrolls to the Data Privacy section.
3. Clicks "Download My Data".
4. A JSON file downloads named my-hyphen-data-{DATE}.json.

Account Anonymization (Admin Console)

This permanently removes all personal information from a reader's account. This action cannot be undone.

1. Open the reader's profile in Readers → Directory → [Reader].
2. Scroll to the GDPR Actions section.
3. Click "Anonymize" (warning/error styled button).
4. A confirmation dialog appears listing what will be deleted:
   • Hash the email address
   • Remove name, phone, profile details
   • Delete OAuth linked accounts and sessions
   • Remove bookmarks and institutional access
   • Anonymize comment author information
5. Confirm the action.
6. The reader's account is anonymized. Their email becomes anon-{hash}@deleted.hyphen.co.
7. If the account was already anonymized, the button shows "Already Anonymized".

Account Deletion (Reader Self-Service via Reader Portal)

1. Reader navigates to Account → Profile on the Reader Portal.
2. Scrolls to the Danger Zone section.
3. Clicks "Delete Account" (red-bordered button).
4. A confirmation dialog appears: "This action is irreversible. All your data, subscriptions, bookmarks, and reading history will be permanently removed."
5. They must enter their current password to confirm their identity.
6. They must type DELETE in the text field to confirm.
7. Click "Permanently Delete" (button is disabled until both password and "DELETE" are entered).
8. The account is deleted, the reader is signed out, and redirected to the homepage.

Deleting a Reader from Admin Console

1. In the Reader Directory, click the Delete button on a reader row.
2. A confirmation modal appears: "This action will anonymize the reader's data. This cannot be undone."
3. Click "Delete Reader" to confirm.
4. The reader's data is anonymized (same as the anonymization process above).

5.16 Reader Moderation (Ban, Unban, Comments)

Banning a Reader

1. Navigate to the reader's profile in Readers → Directory → [Reader].
2. Click "Ban Reader" in the action buttons.
3. A modal appears asking for a Ban Reason (text input).
4. Enter the reason and click "Ban Reader".
5. The reader's status changes to Banned and they see a ban notice on their profile.

Or from the Moderation page:

1. Navigate to Readers → Moderation → Users tab.
2. Find the user and click their profile.
3. Click "Ban" and specify ban type (temporary or permanent) and reason.

Unbanning a Reader

1. Open the banned reader's profile.
2. Click "Unban" in the action buttons.
3. The reader's status returns to Active.

Comment Moderation

1. Navigate to Readers → Moderation.
2. The moderation dashboard shows stats: Pending Comments, New Reports, Approved Today, Banned Users.
3. Use the tabs:
   • Comments tab — review, approve, reject, edit, or delete comments (with bulk actions)
   • Reports tab — review reader reports, resolve or dismiss
   • Users tab — view user moderation records, warnings, ban status, toggle trusted status
   • Settings tab — configure profanity filters, auto-moderation rules, thresholds

5.17 Permissions and RBAC for Admin Users

Different admin roles need different permissions to manage readers. Here are the key permissions:

Tip: If you click a button or try to access a page and nothing happens or you see a blank page, check with your administrator that your role has the required permissions listed above.

5.18 Future Readers Program

The Future Readers Program offers discounted or free subscriptions to students.

Accessing the Program

1. Navigate to Readers → Future Readers in the Admin Console sidebar.
2. You'll see the program dashboard with:
   • Stats: Total Enrollments, Pending Review, Approved, Active Institutes
   • Quick Links: Institutes, Enrollments, Campaigns & Events

Two Routes for Students

Managing Enrollments

1. Click "Review Enrollments" from the dashboard.
2. Review student enrollment applications.
3. Approve or reject entries.
4. Approved students receive discount coupons they can use during checkout.

Managing Institutes

1. Click "Manage Institutes" from the dashboard.
2. Add or manage schools, colleges, and universities participating in the program.

Linked Campaigns

• The dashboard shows campaigns and events linked to the program.
• Each campaign shows: name, status (Draft/Active/Paused/Completed/Archived), institute count, submission count, and pending count.

6. How to Verify It Worked

After setting up or making changes, use these checks to verify everything is working correctly.

Reader Registration Verification

Subscription Verification

Reader Portal Verification

Admin Console Verification

7. Worked Examples

7.1 Example 1: Registering a New Reader and Verifying Account Access

Scenario: A new reader wants to sign up for Hyphen and start reading articles.

Steps:

1. Reader visits the Reader Portal and clicks "Don't have an account?" on the login page.

2. Reader fills in the registration form:

   • Full name: "Priya Sharma"
   • Email: "priya.sharma@example.com"
   • Newsletter checkbox: left checked (default)
   • Terms of Service: checked
   • Clicks "Create Account"

3. Reader checks email and finds a message with a 6-digit OTP (e.g., 482915).

4. Reader enters the OTP on the verification screen and clicks "Verify & Sign In".

5. Reader is now logged in and redirected to the Reader Portal homepage.

6. Admin verifies in Admin Console:

   • Navigate to Readers → Directory
   • Search for "priya.sharma@example.com"
   • Confirm the reader appears with:
     • Status: Active
     • Tier: Free (or Registered)
     • Joined Date: Today's date

7. Reader tests account features:

   • Navigates to Account → Profile — sees their name and email
   • Tries to read a free article — succeeds
   • Tries to read a subscriber-only article — sees paywall/limitation
   • Bookmarks a free article — confirms it appears in Account → Bookmarks

Result: Reader "Priya Sharma" has a working free account. She can read free content, save bookmarks, and comment on articles. She cannot access subscriber-only content until she subscribes.

7.2 Example 2: Assigning a Complimentary Subscription and Checking Reader Portal

Scenario: The editorial team wants to give complimentary access to a contributing author, Rahul Mehta, who already has a free reader account.

Steps:

1. Admin logs into Admin Console and navigates to Readers → Directory.

2. Admin searches for the reader: Types "Rahul Mehta" or his email in the search bar.

3. Admin opens the reader's profile: Clicks the View (→) button.

4. Admin confirms the reader has no active subscription:

   • The Subscription card shows no active plan
   • The "Grant Subscription" button is visible in the action buttons

5. Admin clicks "Grant Subscription" and fills in:

   • Subscription Plan: selects "Annual Digital" from the dropdown
   • Duration: selects "1 Year"
   • Reason: types "Contributing author — complimentary access"
   • Clicks "Grant Subscription"

6. Admin verifies the change:

   • The Subscription card now shows:
     • Plan: Annual Digital
     • Status: Complimentary (badge)
     • Start date: today
     • End date: one year from today
   • The Tier badge changes to Subscriber

7. Verification on Reader Portal (as Rahul):

   • Rahul logs into the Reader Portal
   • Navigates to Account → Subscription
   • Sees: Plan name, status ACTIVE, subscription type Complimentary, and period dates
   • Sees the Your Benefits section with checkmarks for included features
   • Tries reading a subscriber-only article — has full access
   • The Manage Subscription section shows options (but cancellation would be unusual for a complimentary grant)

Result: Rahul now has full subscriber access for one year at no cost. The Admin Console shows the subscription was granted with the reason documented. This can be verified end-to-end in the Reader Portal.

7.3 Example 3: Troubleshooting Why a Reader Is Not Receiving Renewal Reminders

Scenario: A subscriber, Anita Desai, contacts customer support saying she was not notified before her subscription expired. Support needs to investigate.

Steps:

1. Support agent logs into Admin Console and navigates to Readers → Directory.

2. Search for the reader: Types "anita.desai@example.com" in the search bar.

3. Open the reader's profile and check the following:

4. Check 1 — Subscription status:

   • Look at the Subscription card
   • Note the subscription status (Expired? Cancelled? Active?)
   • Note the current period end date — when did it expire?
   • Note the subscription type — if it's Complimentary, renewal reminders may not apply

5. Check 2 — Reader's email preferences:

   • The reader's notification preferences indicate what emails they've opted into
   • Ask Anita to check Account → Preferences → Email Notifications on the Reader Portal
   • Specifically check: is "Renewal Reminders" enabled?
   • If it's disabled, that's why she didn't receive a reminder — she opted out

6. Check 3 — Email delivery:

   • If renewal reminders were enabled, the issue may be email delivery
   • Ask Anita to check her spam/junk folder for emails from Hyphen
   • Check with DevOps if the email/SMTP service is working correctly
   • Check email delivery logs if available

7. Check 4 — Automated task status:

   • Renewal reminder emails are sent by automated tasks (cron jobs)
   • If the automated task is not running, no reminders are sent to anyone
   • Contact your DevOps team to confirm the renewal reminder cron job is active and running on schedule

8. Resolution:

   • If the reader had renewal reminders disabled: Explain to Anita and help her enable it for the future
   • If email delivery failed: Investigate the delivery issue with DevOps
   • If the cron job was not running: Escalate to DevOps to restart it, and consider granting Anita a short extension as goodwill
   • If the subscription type doesn't trigger reminders: Explain the expected behavior

9. Follow-up:

   • If appropriate, grant a short complimentary extension to Anita while she renews
   • Confirm that renewal reminder settings are correct for future cycles
   • Ensure Anita's new subscription (once renewed) has the correct billing period and reminder setup

Result: The support agent has a clear checklist to diagnose why renewal reminders were not received. The root cause is identified and resolved, and the reader is helped back to an active subscription.

7.4 Example 4: Revoking a Reader Session and Verifying Account Security

Scenario: A reader, Vikram Singh, contacts support saying his account may have been compromised. He's seeing articles marked as read that he didn't read, and he wants to secure his account.

Steps:

1. Support agent logs into Admin Console and navigates to Readers → Directory.

2. Search for "Vikram Singh" and open his profile.

3. Check the Devices section:

   • Scroll down to see all active sessions
   • Look for any unfamiliar devices or locations
   • Note the device names (e.g., "Chrome on Windows", "Safari on iPhone"), IP addresses, and last active timestamps
   • If there's a session from an unfamiliar device or IP, this may be the compromised session

4. Revoke suspicious sessions:

   • Click "Revoke" next to each unfamiliar device session
   • The session is immediately terminated — the person using that session is logged out

5. Reset the reader's password:

   • Click the "Reset Password" button in the action buttons at the top
   • A password reset email is sent to Vikram's email address
   • Tell Vikram to check his email and set a new, strong password

6. Verify from the Reader Portal (as Vikram):

   • Vikram logs in with his new password
   • Navigates to Account → Sessions
   • Confirms only his current session is listed (marked as "This device")
   • The suspicious session should no longer appear

7. Additional security steps (if needed):

   • If the compromise is severe, consider temporarily banning the account while investigating
   • Check if there are any unauthorized changes to Vikram's profile (name, email, bio)
   • Check if any suspicious comments were posted from his account
   • Review the reading history for unusual activity

8. Inform the reader:

   • Tell Vikram that the suspicious sessions have been revoked
   • Confirm his password has been reset
   • Advise him to:
     • Not reuse passwords across sites
     • Enable "Require Re-authentication for Sensitive Actions" if available
     • Check his sessions periodically from Account → Sessions

Optional — Admin adjusts security settings:

• Navigate to Settings → Sessions
• Consider reducing the Inactivity Timeout (e.g., from 60 to 30 minutes)
• Consider reducing Maximum Concurrent Devices (e.g., from 5 to 3)
• Enable "Require Re-authentication for Sensitive Actions"

Result: The compromised session is revoked, the password is reset, and Vikram's account is secured. The admin has also reviewed security settings to prevent future incidents.

7.5 Example 5: Handling a GDPR Export and Anonymization Request

Scenario: A reader, Maria Fischer, sends an email to support requesting a copy of all her personal data (GDPR Right of Access) and then asks for her account to be permanently deleted (GDPR Right to Erasure).

Steps:

Part A — Data Export:

1. Support agent logs into Admin Console and navigates to Readers → Directory.

2. Search for "maria.fischer@example.com" and open her profile.

3. Export her data:

   • Scroll to the GDPR Actions section
   • Click "Export Data" (with download icon)
   • A JSON file downloads: hyphen-data-export-{readerId}.json
   • The file contains: profile information, subscription details, bookmarks, comments, and reading history

4. Send the data to Maria:

   • Review the exported file to ensure it contains all expected data
   • Send it to Maria's email as requested (following your organization's data handling procedures)

5. Alternative — Reader self-service:

   • Maria can also download her own data from the Reader Portal
   • Navigate to Account → Preferences → Data Privacy → "Download My Data"
   • A file named my-hyphen-data-{DATE}.json downloads

Part B — Account Anonymization:

6. Confirm the request is legitimate:

   • Verify the request came from Maria (check the email address matches)
   • Follow your organization's GDPR request verification procedure

7. Anonymize the account:

   • On Maria's profile page, scroll to GDPR Actions
   • Click "Anonymize" (warning-styled button)
   • A confirmation dialog appears listing everything that will happen:
     • Hash the email address
     • Remove name, phone, profile details
     • Delete OAuth linked accounts and sessions
     • Remove bookmarks and institutional access
     • Anonymize comment author information
   • Read the list carefully and click "Confirm"

8. Verify anonymization:

   • The page reloads
   • The reader's email now shows as anon-{hash}@deleted.hyphen.co
   • Name, bio, location, website, and phone are blank
   • All sessions are revoked
   • Bookmarks are removed
   • Comments still exist but show an anonymized author
   • The "Anonymize" button now shows "Already Anonymized"

9. Confirm to Maria:

   • Email Maria confirming that:
     • Her data export was provided (Part A)
     • Her account has been permanently anonymized
     • She can no longer log in with her old credentials
     • Her comments remain on the platform but are no longer linked to her identity
   • Note: Maria could also delete her own account from Account → Profile → Danger Zone → Delete Account by entering her password and typing "DELETE" in the confirmation field

Alternative — Reader self-service deletion:

• Maria can navigate to Account → Profile → Danger Zone
• Click "Delete Account"
• Read the warning: "This action is irreversible. All your data, subscriptions, bookmarks, and reading history will be permanently removed."
• Enter her current password for identity verification
• Type DELETE in the confirmation field
• Click "Permanently Delete"
• She is signed out and redirected to the homepage

Result: Maria's GDPR request is fully handled. Her data was exported and provided to her, and her account is permanently anonymized. All personal information has been removed while preserving anonymized comment content for editorial integrity.

8. Common Mistakes and How to Fix Them

Known Limitations

FAQ

This module is access- and entitlements-heavy, so most questions are about who can read what and how a reader controls their own account. Each answer is grounded in the flows above.