How Lived is built, and how it scales

00How to read this

This page combines three kinds of information. Each claim is labelled so engineers know how much weight it can bear.

The build in numbers

Terms such as seeker, guide, intro, package, pay-what-you-can and hold-then-release are defined in the glossary.

01System context

Lived connects seekers (people going through something hard) with guides (vetted people who have lived through the same experience) for paid, pay-what-you-can or free one-to-one peer support. It is explicitly not therapy or professional advice. Today the whole platform is a single Next.js service and a single Postgres database on Render in Frankfurt, calling Stripe and Sentry.

flowchart LR
  S["Seeker"]:::actor
  G["Guide"]:::actor
  A["Admin / moderator"]:::actor
  subgraph R["Render, Frankfurt (EU)"]
    W["lived-app web service
Next.js 16, Node, starter plan"]
    D[("lived-db
Postgres 16, basic-256mb")]
  end
  ST["Stripe (sandbox)
Checkout, PaymentIntents,
Transfers, Refunds"]
  SE["Sentry (EU)
errors and traces"]
  CF["Cloudflare DNS
thelivedapp.com (not cut over)"]
  ZM["ZeptoMail"]:::off
  CAL["Google Calendar /
Microsoft Graph"]:::off
  VID["Video provider"]:::off
  S --> W
  G --> W
  A --> W
  W --> D
  W --> ST
  W --> SE
  CF -.-> W
  W -.->|"not wired"| ZM
  W -.->|"not wired"| CAL
  W -.->|"not chosen"| VID
  classDef actor fill:#e6efe8,stroke:#3d6048,color:#1c2620
  classDef off fill:#f6e6e1,stroke:#a13f2a,color:#1c2620,stroke-dasharray:4 3
  

Current system context. Dashed nodes are declared in configuration but have no code behind them.

02Layers and request lifecycle

The application follows the standard App Router shape: server components read through a thin domain layer in src/lib, client components call server actions to mutate, and every write goes through Prisma. There is no separate API tier.

A typical request

Every page render pays a fixed cost before its own data loads: the root layout is dynamic and SiteHeader calls auth(), getCategories(), isAdminUser() and isSeekerUser() on every request (three database queries, three session reads, no memoisation).

sequenceDiagram
  autonumber
  participant B as Browser
  participant N as Next.js (Render)
  participant L as src/lib read models
  participant P as Prisma
  participant DB as Postgres
  B->>N: GET /guides/[id]
  N->>N: root layout, auth() reads JWT cookie
  N->>P: header queries (categories, isAdmin, isSeeker)
  P->>DB: 3 queries
  N->>L: getGuideProfile, getBookingContext, getReportReasons
  L->>P: queries with includes
  P->>DB: SELECT ...
  N-->>B: streamed RSC payload and HTML
  B->>N: server action bookIntro(guideId, slot)
  N->>N: requireSeeker() and validation
  N->>P: $transaction (re-check slot, create Booking, claim slot, MetricEvent)
  P->>DB: BEGIN ... COMMIT
  N->>N: revalidatePath("/guides/[id]")
  N-->>B: { ok: true } then router refresh
  

Read then mutate. Server actions are the only write path, apart from three Stripe confirmations that run during page render (section 09).

Architectural patterns in use

03Stack and dependencies

A deliberately small dependency set: ten runtime packages. Versions below are the resolved versions in package-lock.json.

Runtime

Development

Scripts

04Repository structure

113 tracked files. Generated and vendored folders are excluded below (node_modules, .next, .git, src/generated/prisma, and the gitignored Prisma agent-skill docs in .agents, .claude/skills, .windsurf).

lived-app/
├── CLAUDE.md                     working rules, launch blockers, done list, roadmap
├── AGENTS.md                     auto-generated Next.js agent note
├── README.md                     overview, local setup, schema notes (refers to a missing lib/payments.ts)
├── render.yaml                   Render Blueprint: lived-db + lived-app web service
├── next.config.ts                empty config wrapped in withSentryConfig
├── prisma.config.ts              Prisma 7 config: schema path, migrations, seed command, DATABASE_URL
├── tsconfig.json                 strict, bundler resolution, @/* alias
├── eslint.config.mjs             flat config, next presets, ignores src/generated
├── postcss.config.mjs            @tailwindcss/postcss
├── .env.example                  env var names and comments
├── .claude/settings.local.json   Claude Code command allowlist
├── docs/verification/
│   ├── 2026-08-29-payments.md            hold-then-release and refund matrix record
│   ├── 2026-08-31-credits.md             credit purchase round trip, double-credit guard
│   └── 2026-08-31-out-of-credits-ui.md   out-of-credits UI record
├── prisma/
│   ├── schema.prisma             30 models, 24 enums
│   ├── seed.ts                   idempotent seed; demo data only when IS_DEMO=true
│   ├── seed-data/categories.ts   23 categories, 153 subcategories, risk flags
│   └── migrations/               9 migrations + migration_lock.toml
├── public/
│   ├── lived-logo.png            brand logo
│   └── file/globe/next/vercel/window.svg   unused scaffold assets
├── scripts/verification/report-guard/
│   ├── README.md                 purpose, usage, PGlite caveat
│   ├── run.ts                    runs real createReport: single | dup | race | clean
│   └── stub-loader.mjs           stubs next/cache and auth for Node execution
└── src/
    ├── instrumentation.ts        server and edge Sentry init, onRequestError
    ├── instrumentation-client.ts browser Sentry init
    ├── app/
    │   ├── layout.tsx            fonts, demo banner, header, footer (force-dynamic)
    │   ├── page.tsx              marketing home, featured guides
    │   ├── globals.css           Tailwind import and @theme tokens
    │   ├── icon.png, apple-icon.png
    │   ├── api/auth/[...nextauth]/route.ts   Auth.js handlers (only API route)
    │   ├── admin/layout.tsx      admin gate, emergency banner
    │   ├── admin/moderation/page.tsx         queue by lifecycle state
    │   ├── admin/moderation/[id]/page.tsx    case detail and controls
    │   ├── bookings/page.tsx     my bookings (both roles), prompts, contribution confirm
    │   ├── cancellation-policy/page.tsx
    │   ├── discover/page.tsx     guide discovery
    │   ├── guides/[id]/page.tsx  guide profile, booking panel, package checkout confirm
    │   ├── login/page.tsx
    │   ├── messages/page.tsx     thread list
    │   ├── messages/[threadId]/page.tsx   thread view, compose, report
    │   ├── signup/guide/page.tsx
    │   ├── signup/seeker/page.tsx
    │   ├── terms/page.tsx
    │   └── wallet/page.tsx       credits balance, buy packs, credits confirm
    ├── components/
    │   ├── admin/case-controls.tsx, admin/resolve-form.tsx
    │   ├── badge-chip.tsx, badge-popover.tsx, category-pill.tsx
    │   ├── booking/booking-panel.tsx
    │   ├── bookings/cancel-button.tsx, complete-button.tsx, contribution-prompt.tsx
    │   ├── discover/discover-client.tsx, guide-card.tsx
    │   ├── login-form.tsx
    │   ├── messages/compose-box.tsx
    │   ├── report/report-button.tsx
    │   ├── signup/guide-signup-form.tsx, seeker-signup-form.tsx
    │   ├── site-header.tsx, site-nav.tsx, site-footer.tsx
    │   └── wallet/buy-credits.tsx
    └── lib/
        ├── auth/auth.ts          Auth.js config
        ├── auth/actions.ts       loginAction, logoutAction
        ├── auth/admin.ts         getAdmin, isAdminUser
        ├── auth/seeker.ts        isSeekerUser (nav only)
        ├── auth/next-auth.d.ts   session.user.id type
        ├── db.ts                 Prisma singleton
        ├── stripe.ts             Stripe client, PLATFORM_FEE_RATE
        ├── config.ts             isDemoMode
        ├── booking.ts, booking-actions.ts
        ├── cancellation.ts, cancellation-actions.ts
        ├── contributions.ts, contribution-actions.ts
        ├── credits.ts, credit-packs.ts, credit-actions.ts
        ├── message-actions.ts, threads.ts
        ├── moderation.ts, moderation-actions.ts, report-reasons.ts
        ├── session-actions.ts, dashboard.ts, guides.ts, categories.ts
        ├── signup-actions.ts, signup-constants.ts, age.ts
        ├── badges.ts, policy-content.ts, terms-content.ts
        └── timezone.ts

Not in the repository: middleware.ts, error and loading boundaries, any API route besides Auth.js, lib/payments.ts (referenced by README and .env.example), tests, CI configuration, a Dockerfile, the HTML prototype, and the build spec (both live outside the repo in ~/Desktop/lived/).

05Data model

Thirty Prisma models across six domains, on Postgres 16. IDs are cuid() strings generated by the client, every table has snake_case naming via @@map, money is Decimal(10,2) in EUR, and every foreign key cascades on update. Where no onDelete is written, Prisma's defaults apply: RESTRICT for required relations, SET NULL for optional ones.

Identity and accounts

erDiagram
  USER ||--o| SEEKER_PROFILE : "has"
  USER ||--o| GUIDE_PROFILE : "has"
  USER ||--o| WALLET : "has"
  USER ||--o{ CREDIT_PURCHASE : "buys"
  USER ||--o{ POLICY_ACCEPTANCE : "accepts"
  USER ||--o{ PERSONAL_DOCUMENT : "uploads"
  USER ||--o{ CALENDAR_CONNECTION : "connects"
  USER ||--o{ NOTIFICATION : "receives"
  USER ||--o{ DELETION_REQUEST : "requests"
  USER |o--o{ CATEGORY : "proposes"
  USER {
    string id PK
    string email UK
    string passwordHash
    string name
    date dateOfBirth
    AccountStatus accountStatus
    UserRole lastActiveRole
    boolean isAdmin
    datetime deletionConfirmedAt
  }
  WALLET {
    string userId PK
    int creditBalance
  }
  CREDIT_PURCHASE {
    string id PK
    string packKey
    int credits
    decimal amountEur
    CreditPurchaseStatus status
    string stripeCheckoutSessionId UK
    string stripePaymentIntentId UK
  }
  

Guide supply and catalogue

erDiagram
  GUIDE_PROFILE ||--o{ GUIDE_CATEGORY : "listed in"
  CATEGORY ||--o{ GUIDE_CATEGORY : "contains"
  CATEGORY ||--o{ SUBCATEGORY : "has"
  CATEGORY ||--o{ SEEKER_PREFERRED_CATEGORY : "preferred by"
  SEEKER_PROFILE ||--o{ SEEKER_PREFERRED_CATEGORY : "prefers"
  GUIDE_PROFILE ||--o{ GUIDE_BADGE : "holds"
  PERSONAL_DOCUMENT |o--o{ GUIDE_BADGE : "evidences"
  GUIDE_PROFILE ||--o{ SESSION_PACKAGE : "offers"
  GUIDE_PROFILE ||--o{ AVAILABILITY_SLOT : "publishes"
  GUIDE_PROFILE ||--o| AVAILABILITY_MODE : "uses"
  GUIDE_PROFILE ||--o{ GUIDE_TRAINING_COMPLETION : "completes"
  TRAINING_MODULE ||--o{ GUIDE_TRAINING_COMPLETION : "completed as"
  GUIDE_PROFILE {
    string id PK
    string ownerId UK
    GuideStatus status
    GuidePricingModel pricingModel
    decimal rateEur
    string stripeAccountId
    boolean stripeChargesEnabled
    string country
    string story
  }
  CATEGORY {
    string id PK
    string name UK
    RiskLevel riskLevel
    boolean requiresEnhancedVetting
    boolean requiresAdvancedSafeguardingBadge
    boolean autoCheckIn
    CategoryStatus status
  }
  AVAILABILITY_SLOT {
    string id PK
    date date
    string time
    string bookingId UK
  }
  

Bookings and money

erDiagram
  SEEKER_PROFILE ||--o{ BOOKING : "books"
  GUIDE_PROFILE ||--o{ BOOKING : "hosts"
  SESSION_PACKAGE |o--o{ BOOKING : "priced by"
  BOOKING |o--o| AVAILABILITY_SLOT : "occupies"
  BOOKING ||--o| CONTRIBUTION : "prompts"
  BOOKING ||--o| REVIEW : "reviewed by"
  GUIDE_PROFILE ||--o{ EARNING : "earns"
  GUIDE_PROFILE ||--o{ PAYOUT : "is paid"
  BOOKING {
    string id PK
    BookingType type
    BookingStatus status
    date dateKey
    string hour
    decimal amountEur
    decimal platformFeeEur
    string stripeCheckoutSessionId UK
    string stripePaymentIntentId UK
    string stripeTransferId UK
    string stripeRefundId UK
    CancelledBy cancelledBy
    decimal refundFraction
    decimal refundEur
  }
  CONTRIBUTION {
    string id PK
    string bookingId UK
    ContributionStatus status
    decimal amountEur
    datetime expiresAt
    string stripeCheckoutSessionId UK
    string stripeTransferId UK
  }
  

Messaging, safety and compliance

erDiagram
  SEEKER_PROFILE ||--o{ THREAD : "participates"
  GUIDE_PROFILE ||--o{ THREAD : "participates"
  THREAD ||--o{ MESSAGE : "contains"
  REPORT_REASON |o--o{ REPORT : "classifies"
  REPORT }o..o| THREAD : "threadId, no FK"
  REPORT }o..|| USER : "reporterId, reportedId, no FK"
  METRIC_EVENT }o..o| USER : "loose ids, no FK"
  THREAD {
    string id PK
    int seekerMsgCount
    int guideMsgCount
    boolean seekerHasUnread
    boolean guideHasUnread
    boolean legalHold
  }
  MESSAGE {
    string id PK
    MessageSender sender
    varchar250 text
  }
  REPORT {
    string id PK
    ReportStatus status
    ReportSeverity severity
    string reasonKey FK
    boolean isEmergency
    EnforcementAction enforcementAction
    json transcriptSnapshot
    string retentionBasis
    boolean legalHold
  }
  

Dotted relationships are logical references stored as plain strings. They survive user deletion by design.

Model catalogue

Migrations

Values computed at read time

Stored counters, maintained by writes: Thread.seekerMsgCount, guideMsgCount, both unread flags, and Wallet.creditBalance.

06State machines

Every status field, its transitions, what triggers them and the guards that apply. All application writes live in src/lib; nothing in src/app or src/components writes directly.

Booking

stateDiagram-v2
  direction LR
  [*] --> CONFIRMED: bookIntro (free intro)
  [*] --> CONFIRMED: bookPackage (FREE or PWYC guide)
  [*] --> Checkout: bookPackage (PAID guide)
  Checkout --> CONFIRMED: confirmPackageCheckout on return page
  Checkout --> [*]: abandoned, nothing recorded
  CONFIRMED --> COMPLETED: completeBooking (guide)
  CONFIRMED --> CANCELLED: cancelBooking (either party)
  COMPLETED --> [*]
  CANCELLED --> [*]
  

For pay-what-you-can bookings the schema says amountEur is filled once the contribution resolves. No code does this, so PWYC bookings always look uncharged.

Contribution (pay-what-you-can)

stateDiagram-v2
  direction LR
  [*] --> PROMPTED: completeBooking, PWYC package, expires in 7 days
  PROMPTED --> MADE: makeContribution with 0 EUR
  PROMPTED --> Checkout: makeContribution above 0
  Checkout --> MADE: confirmContributionCheckout, then 85 percent transfer
  PROMPTED --> SKIPPED: skipContribution
  PROMPTED --> EXPIRED: lazily when the seeker opens /bookings
  

Ownership guards apply to make and skip. The paid confirmation has no caller check, takes the transfer destination from the guide_id URL parameter, does not check expiry, and updates without a conditional claim (F01).

Credit purchase and wallet

stateDiagram-v2
  direction LR
  [*] --> PENDING: startCreditsCheckout creates session then row
  PENDING --> COMPLETED: confirmCreditsCheckout, atomic claim, wallet upsert
  PENDING --> PENDING: tab closed or unpaid, stays forever
  

Wallet.creditBalance goes up in confirmCreditsCheckout and down by one in sendMessage when the seeker has used their five free messages, via an updateMany guarded by creditBalance > 0. Spends are not recorded individually.

Report (moderation case)

stateDiagram-v2
  direction LR
  [*] --> SUBMITTED: createReport (lock, per-reason guard, emergency routing)
  SUBMITTED --> UNDER_REVIEW: claimReport (admin)
  UNDER_REVIEW --> ACTIONED: resolveReport with enforcement
  UNDER_REVIEW --> DISMISSED: resolveReport with NONE
  ACTIONED --> UNDER_REVIEW: markAppealed
  DISMISSED --> UNDER_REVIEW: markAppealed
  

• Severity: HIGH on emergency creation, otherwise LOW; changed by setSeverity or escalateToEmergency.
• Emergency: only ever set to true (at creation, on escalation, or by ESCALATED_EMERGENCY). Sets legalHold and notifies every active admin.
• Appeal: markAppealed sets PENDING and reopens; resolveReport then always writes REJECTED, even if the outcome changes. UPHELD is never written (F10).
• Enforcement: suspension or removal sets user SUSPENDED and guide SUSPENDED; CONTENT_REMOVED sets thread legal hold only; WARNING and NONE notify only. There is no distinct "removed" state.
• Lift: liftEnforcement sets user ACTIVE and guide APPROVED regardless of the guide's previous status, and records nothing on the report (F09).

Account and guide status

stateDiagram-v2
  [*] --> ACTIVE: signup
  ACTIVE --> SUSPENDED: applyEnforcement
  SUSPENDED --> ACTIVE: liftEnforcement
  ACTIVE --> PENDING_DELETION: not built
  PENDING_DELETION --> DELETED: not built
    

stateDiagram-v2
  [*] --> PENDING: guide signup
  PENDING --> APPROVED: seed only, no admin action
  PENDING --> REJECTED: never written
  APPROVED --> SUSPENDED: applyEnforcement
  SUSPENDED --> APPROVED: liftEnforcement
    

Other stateful fields

• Thread: counters and unread flags change on send; the viewer's unread flag clears when they open the thread; legalHold is set by emergencies and content removal and never cleared. No application code creates threads.
• Training, badges, documents: seed only. Nothing aggregates module completion into SAFETY_TRAINED.
• Blocks: no model, enum or code.
• Never written by the app: Category PENDING and REJECTED, Payout, Earning, DeletionRequest, CalendarConnection, AvailabilityMode, User.lastActiveRole, Review (seed only), Notification.readAt, SessionPackage and AvailabilitySlot creation (seed only).

07Routes and server actions

Thirteen pages, two layouts and one Auth.js route handler. There is no middleware, no error.tsx, not-found.tsx or loading.tsx, and every route is dynamic because the root layout sets force-dynamic.

Missing areas: guide dashboard, profile editing, availability and package management, Stripe Connect onboarding, training, document upload, seeker account and settings, notifications, video sessions, admin areas beyond moderation.

Server actions

Because the three confirm functions are exported from "use server" modules, Next.js may also expose them as callable action endpoints (inferred, not verified against the action manifest).

08Auth, access control and onboarding

Auth.js v5 with a credentials provider and stateless JWT sessions. Roles are derived from which profiles a user owns, plus a single admin flag. All gating happens in pages, layouts and actions; there is no middleware.

Access matrix

A suspended user with a live token passes every non-admin check, because no action checks accountStatus.

Signup flows

Guide lifecycle capabilities

09Payments

Stripe Connect using separate charges and transfers, the "hold then release" model: the platform account takes the full payment through hosted Checkout and transfers the guide's 85% only when the session is completed. Everything runs in Stripe test mode. The model touches e-money rules and needs solicitor and Stripe compliance sign-off before production.

Where money rules are defined

Paid package: book, complete, release

sequenceDiagram
  autonumber
  actor S as Seeker
  participant A as Next.js actions
  participant ST as Stripe (platform)
  participant DB as Postgres
  actor G as Guide
  S->>A: bookPackage(guide, package, slot)
  A->>ST: checkout.sessions.create (price, metadata)
  A-->>S: redirect to Stripe Checkout
  S->>ST: pays
  ST-->>S: redirect /guides/[id]?checkout_session_id=...
  S->>A: page render runs confirmPackageCheckout
  A->>DB: lookup by checkout session id (idempotency)
  A->>ST: sessions.retrieve, require paid
  A->>DB: transaction: re-check slot, create Booking CONFIRMED with amount and 15 percent fee, claim slot, metrics
  Note over A,DB: If the tab closes before this point, nothing is recorded
  G->>A: completeBooking(bookingId)
  A->>DB: transaction: COMPLETED, metrics, PWYC prompt if relevant
  A->>ST: paymentIntents.retrieve then transfers.create 85 percent to guide account
  A->>DB: store stripeTransferId
  Note over A,ST: If the transfer fails, the booking stays COMPLETED with no transfer and cannot be retried
  

Cancellation and refunds

sequenceDiagram
  autonumber
  actor U as Seeker or guide
  participant A as cancelBooking
  participant ST as Stripe
  participant DB as Postgres
  U->>A: previewCancellation then cancelBooking
  A->>A: computeRefund(hours until slot in guide timezone, canceller)
  A->>ST: refunds.create (seeker share) if above 0
  A->>ST: transfers.create (guide share) if above 0
  A->>DB: transaction: CANCELLED with refund fields and Stripe ids, free slot, metric
  Note over A,ST: No conditional claim and no idempotency key, so a double submit can refund twice
  

Completed bookings cannot be cancelled. There is no refund path for credits or contributions, and moderation suspensions do not cancel or refund anything.

Credits

startCreditsCheckout resolves the pack server-side, creates a platform Checkout Session with metadata {userId, packKey}, inserts a PENDING CreditPurchase and redirects. On return, confirmCreditsCheckout returns early if already COMPLETED, requires a paid session, then in one transaction claims the row with updateMany where status = PENDING, upserts the wallet increment and writes CREDITS_PURCHASED. Double-crediting is prevented; lost redirects are not recovered.

Pay-what-you-can

Completing a PWYC package creates a PROMPTED contribution with a 7-day expiry. The seeker can give €0 (recorded as MADE, no Stripe call), skip, or pay any amount above zero through Checkout. On return, confirmContributionCheckout records the amount from amount_total and immediately transfers 85% to the guide found from the URL's guide_id. The platform fee is not stored, and Booking.amountEur is never updated for PWYC bookings, so revenue reporting cannot be reconstructed from bookings alone.

10Messaging and sessions

Messaging works end to end for existing threads: seekers get five free messages per thread and then spend one credit per message; guides always message free. Delivery is by server action and page revalidation, with no realtime channel. Video sessions are not built.

Send path

flowchart TD
  A["ComposeBox submit"] --> B{"sendMessage: logged in and thread participant?"}
  B -- "no" --> X["Conversation not found"]
  B -- "yes" --> C{"Text 1 to 250 chars?"}
  C -- "no" --> Y["Validation error"]
  C -- "yes" --> D{"Sender is seeker?"}
  D -- "guide" --> E["guideMsgCount +1, seekerHasUnread = true"]
  D -- "seeker" --> F{"updateMany where seekerMsgCount below 5"}
  F -- "1 row" --> G["Free message used, guideHasUnread = true"]
  F -- "0 rows" --> H{"wallet.updateMany where creditBalance above 0"}
  H -- "1 row" --> I["Credit spent, count +1, guideHasUnread = true"]
  H -- "0 rows" --> Z["OutOfCreditsError, transaction rolls back"]
  E --> M["message.create"]
  G --> M
  I --> M
  M --> R["revalidatePath thread and list"]
  

One transaction at READ COMMITTED. Conditional updates provide the concurrency guarantee.

Sessions

Today a session is a booking row. The guide clicks "Mark complete" manually; there is no check that the session time has passed and no automatic completion. The intro length (15 minutes) exists only in copy; package durations come from SessionPackage.durationMinutes.

11Moderation and safety

Report intake and the admin case workflow are the most mature part of the build, with protection against duplicate reports at application and database level. Blocking, notifications, email alerts and a proper permissions model are not built.

Report intake

• Reasons live in report_reasons: off_platform, harassment, sexual_inappropriate, hate, spam_scam, impersonation, clinical_advice, wellbeing_concern, immediate_danger (the only emergency), other.
• Entry points: the guide profile (logged in, not own profile, thread attached if one exists) and the thread view. The modal shows reason descriptions, an emergency-services notice for immediate danger, and an optional detail field capped at 1,000 characters.
• Validation: logged in, not self, reason active, reported user exists. The emergency flag comes from the reason row, never the client. A transcript snapshot is taken only if the reporter is a participant in the cited thread.
• Duplicate guard: inside the transaction, an advisory lock on the reporter and reported pair, then at most one open report per reason. Reason other is capped at five open. The partial unique index backs this up, and unique violations (P2002 or SQLSTATE 23505) map to the same friendly error.
• Emergencies: severity HIGH, legal hold on the report and cited thread, and a Notification row for every active admin. Nobody reads those rows; the only visible signal is the red banner in the admin layout.

Admin workflow

The queue at /admin/moderation sorts emergencies first, then oldest, grouped by lifecycle state, with repeat-offence banners. The case page shows both parties, reason, transcript snapshot, retention basis, legal hold, other cases against the same person and notified flags. Admins can claim, write notes, set severity, escalate, resolve (reason of at least 10 characters), mark appealed and lift enforcement.

Pending legal sign-off: the emergency escalation procedure (country-specific safeguarding contacts and steps) is a policy document requiring professional review. The hooks exist; the procedure does not.

12GDPR, retention and metrics

The schema has hooks for retention and deletion; none of the processes behind them exist. Metrics are written into an append-only event table that nothing reads yet.

Retention fields

Metric events

Events are written inside the same transaction as the change they describe, which keeps them consistent. There are no consumers: no dashboards, exports or aggregate queries.

13UI and design system

Tailwind v4 with design tokens lifted from the HTML prototype into an @theme block in globals.css. Inter for text, Playfair Display for headings, loaded through next/font. No component library, icon set or dark mode.

Radius: --radius-card 16px, --radius-sm 10px; two card shadows. Breakpoints are Tailwind defaults (the nav comment assumes the prototype's 720px, but Tailwind's md is 768px). A few colours are hard-coded outside the tokens in the footer, home page and avatar fallback.

Components

State and forms: local React state only (useState, useTransition, useActionState), router.refresh() after mutations, no context providers or data-fetching libraries. Validation is native HTML attributes on the client and hand-written checks on the server; there is no schema library. Small helpers such as fmt() are duplicated across page files.

14Integrations

15Security posture

The fundamentals are sound: React escapes output, the one raw SQL statement is parameterised, secrets stay out of the repo, and admin routes are checked against the database. The gaps are in the perimeter (headers, rate limits, middleware) and in a handful of unauthenticated or under-validated entry points.

16Performance and data access

Fine at demo scale. Nothing is cached, nothing is paginated, and several read paths load whole tables into memory. These are the first things to break as usage grows.

17Errors and observability

18Deploy, environments and operations

Infrastructure is declared as code in render.yaml. A push to main builds and deploys automatically; migrations run before the new version starts. There is one environment: the demo/staging service. Environment variable changes alone do not trigger a deploy; a manual redeploy is required.

flowchart LR
  DEV["Local: next dev + prisma dev
or Docker Postgres 16"] -->|"git push main"| GH["GitHub
THELIVEDAPP-LTD/lived-app"]
  GH -->|"auto-deploy on commit"| B["Render build
npm install (postinstall: prisma generate)
next build"]
  B --> PD["preDeploy
prisma migrate deploy"]
  PD --> RUN["next start
lived-app, starter plan"]
  RUN --> DB[("lived-db
Postgres 16")]
  SH["Render Shell
npm run db:seed (manual)"] -.-> DB
  

Environment variables

Seed data

Always seeded (every environment, idempotent upserts): 23 categories (16 standard, 6 sensitive of which 3 auto check-in, 1 high-risk "Domestic Abuse & Coercive Control"), 153 subcategories, 6 training modules and 10 report reasons.

Only when IS_DEMO=true: 10 demo users sharing one password, 5 APPROVED guides with safety training and badges (Maya paid, James pay-what-you-can, Aisha free, plus Victor and Wes), 2 seekers, an admin, 7 session packages, 45 availability slots relative to the seed date, a wallet, one completed intro with a review, 2 threads (one is the out-of-credits fixture), and 8 moderation cases across all states.

Demo logins (staging only)

All demo accounts share the password demo-password. Other seeded users (James, Aisha, Victor, Wes, Rob, Nadia) use the same password; check prisma/seed.ts for their exact addresses. Stripe connected-account details in the seed are deliberately left out of this document.

Operational references

Render web service srv-da72k1e7bikc73emf3h0, database dpg-da72jmu7bikc73eme1n0-a, Blueprint exs-da72btvavr4c738941g0. Domains thelivedapp.com and the-lived-app.com are on Cloudflare; the app still serves from lived-app.onrender.com.

19Testing and quality

There are no automated tests and no CI. Quality so far rests on strict TypeScript, ESLint, and manual live verification recorded in docs/verification.

20Git state

Remote github.com/THELIVEDAPP-LTD/lived-app, branch main in sync with origin, clean working tree, no stashes. 35 commits from 26 Aug to 10 Sep 2026. Latest: d5ae62e "fix(report): re-add the advisory lock via $executeRaw, verified locally first".

21Prototype vs production

The single-file HTML prototype (about 6,500 lines, outside the repo) is the functional reference. Production covers discovery, profiles, booking, payments, messaging, reporting and moderation. The list below is what the prototype has and production does not; the mapping from prototype function names is inferred.

22Findings register

Every defect, risk and gap from the audit, ranked. Critical items can lose or misdirect money, or let a sanctioned user keep acting. High items block launch or break a core journey. Medium items are hardening and scale work.

23Target production architecture

The target keeps what works: one Next.js codebase, Prisma on Postgres, Render in Frankfurt, Stripe Connect with hold-then-release. It adds the pieces a money-moving, safety-critical marketplace needs: an edge, webhooks, a worker with scheduled jobs, a shared cache and queue, realtime, file storage, and separate environments. Items marked "locked" come from the founder's decision log; everything else is proposed.

flowchart TB
  U["Seekers, guides, moderators"] --> CF["Cloudflare
DNS, TLS, WAF, bot and rate rules, CDN"]
  CF --> WEB
  subgraph RENDER["Render, Frankfurt (production)"]
    WEB["Web service, 2+ instances
Next.js pages, server actions,
webhook, health and realtime-auth routes"]
    WK["Background worker
outbox and job consumer"]
    CRON["Cron jobs
sweeps, reconciliation, rollups"]
    KV[("Key Value (Redis)
rate limits, queue, pub/sub, cache")]
    POOL["Connection pooler"]
    PG[("Postgres primary
point-in-time recovery")]
    RR[("Read replica
admin and analytics")]
  end
  WEB --> KV
  WK --> KV
  WEB --> POOL
  WK --> POOL
  CRON --> POOL
  POOL --> PG
  PG -.-> RR
  ST["Stripe Connect"] -->|"signed webhooks"| WEB
  WEB --> ST
  WK --> ST
  WK --> ZM["ZeptoMail"]
  WK --> CAL["Google Calendar,
Microsoft Graph"]
  WEB --> OBJ["EU object storage
documents and exports, encrypted"]
  WEB --> RT["Realtime transport"]
  WEB --> VID["Video provider"]
  WEB --> OBS["Sentry EU, log drain, uptime"]
  WK --> OBS
  

Target production topology. A staging copy mirrors it at smaller sizes with Stripe in test mode and demo seed allowed.

Environments

Use Render environment groups so secrets are managed once per environment, and set AUTH_URL and a new APP_URL per environment.

Application tier

• Stateless web instances. JWT sessions and no in-memory state already make horizontal scaling straightforward, once rate limits and pub/sub move to Redis.
• Middleware for security headers, authenticated-area redirects and request ids.
• A shared guard module: requireUser, requireActiveUser, requireSeeker, requireGuide, requirePermission, and one isBookable policy. Every action starts with one of them.
• Schema-validated inputs for every action (a single validation library, shared between client and server).
• Route handlers only where server actions do not fit: /api/webhooks/stripe, /api/webhooks/calendar, /api/health, realtime token issuing, data export download.
• Transactional outbox: any side effect (email, notification, transfer, calendar write, metric rollup) is recorded as a job row in the same transaction as the state change, then executed by the worker. This removes every "Stripe after commit with no retry" path.

Background jobs

Payments, target flow

sequenceDiagram
  autonumber
  actor S as Seeker
  participant W as Web
  participant ST as Stripe
  participant DB as Postgres
  participant Q as Worker
  S->>W: bookPackage
  W->>DB: create Booking PENDING_PAYMENT holding the slot, expires in 30 min
  W->>ST: checkout.sessions.create with idempotency key
  S->>ST: pays
  ST->>W: POST /api/webhooks/stripe checkout.session.completed
  W->>W: verify signature
  W->>DB: insert StripeEvent (id unique) and outbox job in one transaction
  W-->>ST: 200
  Q->>DB: claim job, Booking PENDING_PAYMENT to CONFIRMED, ledger entries
  ST-->>S: redirect to return page
  S->>W: return page shows status from DB (authenticated)
  

• Release: when the session completes, an outbox job sends the 85% transfer with an idempotency key and writes the ledger.
• Connect onboarding: create connected accounts and onboarding links from the guide portal; charges_enabled and payouts_enabled come only from account.updated.
• Ledger: one row per money movement (charge, platform fee, transfer, refund, contribution, credit purchase, credit spend, payout), written in the same transaction as the state change. The existing Earning and Payout models can be the starting point.
• Payout schedule: monthly as standard with an optional fortnightly early payout that carries a 20% platform fee instead of 15% (locked policy, from the legal documents).
• Block-driven cancellation: two transactions around the Stripe refund with a CANCELLING state and a CancellationReason field (locked).
• Compliance gate: live mode only after solicitor and Stripe confirm the hold-then-release model does not require an e-money licence (locked).

Identity and access

• Email verification before booking or messaging, and password reset, both via ZeptoMail with single-use hashed tokens.
• Normalised emails and a case-insensitive unique index.
• Session revocation through a sessionVersion checked in the session callback.
• Rate limits on login, signup, reset, checkout creation, messaging and reporting, stored in Redis.
• Staff roles replacing isAdmin: for example support, moderator, senior moderator and administrator, each with explicit permissions; multi-moderator assignment; an append-only audit log of every staff action, including every view of a transcript or personal document.
• Google sign-in later, from the same Google Cloud project as calendar OAuth (locked sequencing).

Guide onboarding pipeline

flowchart LR
  A["Application
story, location, languages,
categories, pricing model"] --> B{"Staff review"}
  B -- "reject with reason" --> R["REJECTED"]
  B -- "approve" --> C["Required training
safety basics, crisis awareness,
boundaries"]
  C --> D["SAFETY_TRAINED badge
awarded automatically"]
  D --> E{"Category risk rules"}
  E -- "enhanced vetting or
high-risk category" --> F["ID verification and
advanced safeguarding"]
  E -- "standard" --> G
  F --> G["Stripe Connect onboarding
(paid and PWYC guides)"]
  G --> H["Availability, packages,
calendar sync"]
  H --> I["Bookable
single isBookable policy"]
  

Badges stay independent, not a ladder (locked). Lived-experience evidence and ID documents go to encrypted EU object storage, are reviewed by staff with every access logged, and are swept after verification according to the retention register.

Messaging, notifications and sessions

• Thread creation from the guide profile and after booking, respecting blocks.
• Realtime delivery of messages, unread counts and session state (locked requirement; provider open).
• Notification centre reading the existing Notification table, with email fallback and user preferences.
• Video sessions inside the thread page with the locked timing rules; a SessionRoom record per booking storing provider room id, join times and end time for disputes.
• Reviews after completion, emotion-led language with hidden numeric weights (locked).

Data protection

• Retention register implemented as code: each data class has a period, a legal basis and a sweep. Legal hold overrides sweeps.
• Subject access export and account deletion pipelines using the existing DeletionRequest model and account states.
• Encryption: provider-managed at rest for the database and storage, plus application-level encryption for OAuth tokens and document keys.
• Processor register kept alongside the retention register, with EU residency for every new vendor.
• Policy re-acceptance on version change, reading PolicyAcceptance.

Operations and quality

• /api/health checking the database and Redis, wired to Render's health check and an external uptime monitor.
• Structured JSON logs with request ids, shipped to a log drain; Sentry with lower trace sampling, PII scrubbing and user ids.
• Alerts on webhook failures, job retries exhausted, emergency reports unacknowledged, and error-rate spikes.
• Point-in-time recovery on production, a tested restore runbook, and the database IP allow-list set.
• CI on every pull request: lint, type-check, unit tests, integration tests against Postgres 16 and stripe-mock, a migration drift check that protects the partial index, and a Playwright smoke suite for sign-up, booking, payment, messaging and reporting.

Proposed schema additions

24Scaling path

Lived's load profile is modest per user (a handful of bookings and messages per week) but spiky around evenings and session start times. Correctness matters far more than throughput at launch. Scale in stages, triggered by measurements rather than dates.

Signals to watch

• p95 latency of Discover and thread pages; database CPU and connection count; pool wait time.
• Webhook processing lag and job queue depth.
• Realtime concurrent connections around session start times.
• Moderation queue age, especially emergency acknowledgement time.

Multi-region is not needed: users and data residency are EU. Keep a single Frankfurt region and invest in backups and recovery time instead.

25Roadmap to production

Phases are ordered by dependency. Each phase ends with live verification on the staging environment, which is the project's acceptance standard.

26Decisions and open questions

Locked decisions the build must honour

Open questions for sign-off

27Glossary