Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.litigationlabs.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Purpose & Scope

LitigationLabs delivers an authenticated Next.js experience that lets trial teams rehearse courtroom strategy inside the CaseSim workspace. The system streams user questions through a multi-agent courtroom simulation, persists transcripts and scores, and exposes admin knobs through Payload CMS.

​
Primary User Journeys

  • Advocate rehearsal — An authenticated user enters the CaseSim dashboard, selects a scenario, and walks through questioning a witness while reacting to objections and judge rulings.
  • Scenario design — Internal staff seed/modify scenarios, witness affidavits, elicits, and agent prompt templates inside Payload CMS collections.
  • Session review — Players and instructors revisit transcripts, metrics, and unlocked facts for feedback loops.

​
Component Stack Overview

  1. Client Shell (Next.js App Router + React 19)
    • app/(site)/dashboard renders the authenticated dashboard shell and CaseSim tooling.
    • Client-side components (components/layout/dashboard-shell.tsx, components/casesim/*) manage navigation, optimistic UI, and transcript display.
    • NextAuth session is fetched server-side before rendering CaseSim, keeping auth out of the client bundle.
  2. Experience APIs (Next.js Route Handlers)
    • app/(site)/api/courtroom/turn orchestrates each player utterance.
    • Adjacent routes (e.g., /api/courtroom/witness, /api/sessions, /api/site/scenarios) expose CRUD access to sessions and content for the UI.
    • All handlers are server-side modules that can call lib services directly with no network hop cost inside Vercel.
  3. Domain Services (lib/payload.ts)
    • Encapsulate Payload CMS (Postgres) reads/writes for scenarios, sessions, and agent configs, with in-memory fallbacks for local dev.
    • Enforce schema validation (Zod) for phases, roles, and objection types before persisting Sessions.
  4. AI Agent Layer (lib/courtroom/*)
    • orchestrator.ts coordinates the player turn, OCA objections, judge rulings, witness answers, scoring, and metrics.
    • prompts.ts renders dynamic system prompts per agent, injecting scenario + transcript context and JSON schemas.
    • gateway.ts pipes requests through the Vercel AI Gateway, tagging each agent via x-vercel-ai-route for observability.
  5. Persistence & Identity
    • NextAuth stores user identities in the same Postgres instance or Neon, using the schema under db/nextauth-schema.sql.
    • Payload CMS hosts scenarios, agent configs, and courtroom sessions. When Payload is unreachable, lib/payload.ts falls back to an in-memory Map to keep the simulator viable in local environments.
  6. External Integrations
    • Vercel AI Gateway (model multiplexing, rate limiting, API key gating).
    • SMTP/Google/Apple identity providers via NextAuth.

​
Request & Data Lifecycles

​
Authenticated Navigation

  1. User hits /dashboard/casesim.
  2. CaseSimPage calls getServerSession(authOptions); anonymous users are redirected home.
  3. The client renders DashboardShell, which loads child panels and begins fetching session/scenario data via /api routes.

​
Player Turn (/api/courtroom/turn)

  1. Client posts { sessionId, userUtterance }.
  2. Route handler reads the latest CourtroomSession via getSessionById and pulls the linked Scenario from Payload CMS (or the fallback sample cache).
  3. handleTurn executes:
    • Adds the player question to the transcript.
    • Determines OCA mode (objection vs. examination) from session phase + witness ownership.
    • Optionally calls the Opposing Counsel agent via AI Gateway using the system prompt assembled in buildOCSystemPrompt. JSON schema enforcement happens by parsing with ocaObjectionResponseSchema.
    • If OCA objects, the Judge agent is invoked with buildJudgeSystemPrompt; the ruling controls whether the witness answers.
    • Witness answers go through buildWitnessSystemPrompt, pointing each witness at their affidavit, demeanor, and elicits.
    • computeScoreDeltaFromAnswer tallies unlocked elicits, produces score deltas, and updates session metrics (lag, questions asked, objection stats).
  4. Updated session is persisted via saveSession and returned to the client alongside the synthesized CourtEvents for real-time rendering.

​
Witness Selection (/api/courtroom/witness)

Validates that the witness exists in the chosen scenario before mutating currentWitnessId on the session.

​
Scenario & Session Discovery

/api/site/scenarios and /api/sessions wrap the underlying Payload finders to populate CaseSim menus, dashboards, and resume experiences.

​
Data Model Highlights

  • Scenario (lib/courtroom/types.ts): top-level metadata plus forAgents.witnesses[], each containing affidavits, tendencies, and per-witness elicits (key facts).
  • CourtroomSession: tracks player side, current phase (pretrial -> direct -> cross -> ...), current witness, transcript (CourtEvent[]), score state, and per-turn metrics.
  • AgentConfig: fetched live (1-minute cache) so instructional staff can hot-edit prompts, intentional error rates, and model overrides without redeploying code.

​
Deployment & Environment

  • Runtime: Next.js 16 (App Router) on Vercel, leveraging the Edge/Node runtimes depending on route needs.
  • CMS: Payload CMS co-deployed under /app/(payload) with an isolated admin UI at /admin.
  • Data: Neon or self-hosted Postgres backing NextAuth + Payload. Local development may skip Payload by using sample data.
  • Configuration: .env.local drives NextAuth providers, Payload, and AI Gateway credentials.

​
Operational Considerations

  • Latency budgets: handleTurn records lagMs for the objection + witness pipeline; these metrics can later feed telemetry dashboards.
  • Resilience: Each agent call is wrapped in try/catch. Failures degrade gracefully by emitting system events while allowing the rest of the turn to proceed.
  • Prompt safety: All AI responses are forced through JSON schemas when applicable (OCA, Judge). Witness answers are constrained through scenario affidavits.
  • Security: All CaseSim routes require a NextAuth session. Payload admin routes live under (payload) to isolate them from public site traffic.
  • Scalability: Stateless route handlers keep concurrency high. Long-running operations (LLM calls) happen server-side so browser clients stay responsive.