Ledn full-stack prototype (unified frictions)

Private submission repo for the Ledn engineering challenge. This prototype implements all five frictions from FRICTIONS.md as one coherent “treasury / multi-leg operations” story:

Friction	What we built
Cascading integration failure	Persisted saga with ledger → compliance → clearing steps, retries, compensations (ledger release), idempotency keys, append-only step log, WebSocket timeline updates.
Settlement timing trap	Booked vs settled: clearing creates a pending settlement leg that completes after a delay; liquidity read model exposes believed vs settlement-adjusted available and an exposure mismatch flag.
Blind spot under pressure	Bounded queue with priority lanes (critical vs normal), dropped normal ops when overloaded, synthetic surge injector, rolling p50/p95 step latency, degraded banner, circuit breaker on clearing.
Fragile data feed	Mock feed with healthy / delayed / stale / unavailable scenarios, confidence and staleness policy gating clearing, WebSocket tick stream.
Invisible liquidity dashboard	Single live dashboard (available / held / in-flight / pending settlement / feed / circuit) with REST + WebSocket refresh.

Stack

• Backend: NestJS (TypeScript), TypeORM, SQLite (file DB, zero Docker requirement), Socket.IO gateway.
• Frontend: Next.js 15 (App Router, TypeScript), TanStack Query, socket.io-client.
• Shared: packages/shared — Zod schemas / types used by API validation and the UI.

Prerequisites

• Node.js 20+ (tested on Node 22).
• npm 9+ (workspaces).

Install

npm install

postinstall builds @ledn/shared so @ledn/api can import its dist output.

Run locally

Terminal 1 — API (port 4000 by default):

npm run dev:api

Terminal 2 — Web (port 3000):

npm run dev:web

Or both:

npm run dev

Copy .env.example values into apps/web/.env.local (for NEXT_PUBLIC_API_URL) and optionally apps/api/.env for tuning. CORS allows WEB_ORIGIN (comma-separated list supported).

Build & test

npm run build
npm run test

Architecture (short)

flowchart LR
  subgraph ui [Next.js]
    Dash[Liquidity dashboard]
    Ops[Operations + timeline]
    FeedCtl[Feed scenarios]
    Stress[Surge + metrics]
  end
  subgraph api [NestJS]
    REST[REST controllers]
    WS[Socket.IO gateway]
    Saga[Saga orchestrator + queue]
    Mock[Mock ledger/compliance/clearing]
    Settle[Settlement timer]
    Feed[MarketData tick + policy]
  end
  DB[(SQLite)]
  ui --> REST
  ui --> WS
  REST --> Saga
  Saga --> Mock
  Saga --> Settle
  Saga --> Feed
  Saga --> DB
  Settle --> DB

Loading

• REST for commands (POST /operations, POST /admin/..., GET /liquidity/snapshot, GET /metrics).
• WebSocket broadcasts liquidity, saga, metrics, and feed events for live UI.

Trade-offs (intentional)

• SQLite + synchronize: true: fastest local demo; not a production persistence choice.
• In-process queue + timers: no Redis/NATS in this repo; behavior and backpressure are still explicit and visible.
• Single-tenant mock domain: focuses on observability and policy, not multi-tenant auth.

Original challenge & submission

The open-ended prompt and evaluation criteria live in the Ledn README you received with the challenge (see also FRICTIONS.md). For submission: private GitHub repo, invite @ledn-reviewer, include this README, and record the Loom walkthrough as requested.