Admin Panel — Technical Reference¶

Status: Transitional. The admin panel is a working internal tool, but a full redesign is planned. The redesign will replace direct PostgreSQL access with calls to internal service APIs (Auth Center, Payment Manager, KYC Service, Notifications Service).

Overview¶

SvelteKit 5 web application for internal operators, finance staff, and support. Current responsibilities:

User management and profile viewing
KYC verification workflow (review, approve, reject)
Transaction / payment history viewing
Ledger account and balance inspection
Payment Manager limits configuration

Architecture¶

Architecture

Technology Stack¶

Layer	Technology	Version
Framework	SvelteKit	^2.57.0
UI language	Svelte (runes syntax)	^5.55.2
Language	TypeScript	^6.0.2
Styling	Tailwind CSS v4	^4.2.2
Build tool	Vite	^8.0.7
Node adapter	@sveltejs/adapter-node	^5.5.4
DB client	pg	^8.20.0
S3 client	@aws-sdk/client-s3	^3.1030.0
Graph/flow	@xyflow/svelte	^1.5.2

Current Data Access¶

The panel currently accesses PostgreSQL directly (read) and calls the Serverpod internal URL for write operations (approve/reject/block). This is a transitional architecture — the redesign will remove direct DB reads in favour of service API calls.

Authentication for admin users goes through nginx auth_request at /nginx/auth/admin.

Route Structure¶

src/routes/
├── +layout.svelte          ← root layout
├── +layout.server.ts       ← session check
├── +page.svelte            ← dashboard redirect
├── login/                  ← public login page
├── logout/                 ← session clear
├── users/                  ← user list + [userId] detail
├── kyc/                    ← KYC queue + [userId] review
├── ledger/                 ← TigerBeetle ledger viewer
│   ├── overview/           ← summary stats
│   ├── balances/           ← account balances
│   ├── identities/         ← account identity lookup
│   ├── ledgers/            ← ledger list
│   ├── transactions/       ← transaction history
│   └── reconciliation/     ← reconciliation tools
├── payment-manager/        ← PM operational views
│   └── limits/             ← fee/limit rule configuration
└── api/                    ← server-side API routes
    ├── blnk/               ← (legacy ledger proxy)
    └── node-wallets/       ← wallet node endpoints

Design System¶

Color tokens are defined in src/routes/layout.css using Tailwind v4 @theme directives. Do not use raw Tailwind color utilities directly (e.g., blue-600, green-100).

Purpose	Class
Primary action button	`bg-primary hover:bg-primary-dark`
Input/select focus ring	`focus:border-primary focus:ring-1 focus:ring-primary`
Badge — success/active	`bg-success/10 text-success`
Badge — warning	`bg-warning/10 text-warning`
Badge — info	`bg-info/10 text-info`
Badge — error/rejected	`bg-error/10 text-error`
Badge — neutral	`bg-gray-100 text-gray-600`

Badge shape: inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium

Filter panel: bg-white rounded-xl border border-gray-200 p-3 flex flex-wrap gap-2 mb-4

Rules for LLM / AI Coding Assistants¶

Use Svelte 5 runes syntax: $state(), $derived(), $effect() — not Svelte 4 stores (writable, readable, $:)
Tailwind v4: all theme configuration is in CSS @theme { ... } blocks — no tailwind.config.js
No direct DB writes that bypass service APIs in new code — reads from PostgreSQL are transitional and will be removed in the redesign
Auth: /nginx/auth for regular users, /nginx/auth/admin for operators

Current Limitations (Transitional State)¶

Some page loaders read PostgreSQL directly instead of calling Auth Center / PM APIs
After the redesign: all reads go through Auth Center REST API, PM API, KYC Service API
The src/lib/ client utilities will be refactored as service API clients