Admin UI Dashboard
Relevant source files
The following files were used as context for generating this wiki page:
The Admin UI Dashboard is a standalone administrative interface built with Next.js that surfaces the backend management capabilities of the tldw_server project. It serves as a central hub for administrators to monitor system health, manage users and organizations, oversee resource governance, and handle data operations. The interface is designed to provide high-level visibility through stats grids while allowing deep-dives into specific administrative domains.
The dashboard integrates directly with the FastAPI backend through a specialized API client, enabling real-time monitoring of server statistics, incident management, and policy resolution. It supports both single-user and multi-user authentication modes, implementing role-based access control (RBAC) to gate sensitive administrative pages and operations.
Sources: Docs/Architecture.md:2, Docs/Design/plans/2026-03-14-phase2-admin-ui-sprint.md:3-5, Docs/Plans/2026-02-27-admin-ui-review-design.md:14-16
Architecture and Components
The Admin UI is built using a modern frontend stack designed for reliability and maintainability. It follows a pattern of utilizing a page wrapper that disables server-side rendering (SSR) for administrative routes, ensuring that sensitive data is only handled client-side after authentication.
Core Tech Stack
- Framework: Next.js (App Router and Pages Router support)
- Language: TypeScript
- Styling: Tailwind CSS
- UI Components: Ant Design (v5/v6)
- Testing: Vitest and Bun-based test runner
- Data Fetching: Custom
TldwApiClientand React hooks
Sources: Docs/Design/plans/2026-03-14-phase2-admin-ui-sprint.md:5-10, Docs/Plans/2026-02-27-admin-ui-review-design.md:15-18
Component Communication Flow
The following diagram illustrates how the Admin UI components interact with the backend API and shared services:
Key Administrative Modules
The Admin UI is divided into specialized modules that handle different facets of system administration.
Monitoring and Alerts
The monitoring module provides real-time health data and alerting configurations. It tracks system stats such as active users, storage utilization, and session counts. It also surfaces security alerts and allows administrators to define alert rules based on specific metrics.
- Endpoints:
GET /admin/stats,GET /admin/monitoring/alert-rules,GET /admin/security/alert-status. - Components:
StatusBanner,HealthGrid,AlertRulesTable.
Sources: Docs/Design/plans/2026-03-14-phase2-admin-ui-sprint.md:83-93, Docs/Product/Completed/Plans/IMPLEMENTATION_PLAN_hci_09_information_architecture.md:28-32
Resource Governance
This section manages the "Resource Governor" which controls rate limiting, token usage, and policy resolution.
- Policy Management: CRUD operations for user, organization, and global policies.
- Simulation: An impact simulation tool to show how policy changes affect users and requests.
- Analytics: Cards rendering throttle event counts and rate limit rejection metrics.
Sources: admin-ui/Release_Checklist.md:73-78, Docs/Product/Completed/Plans/IMPLEMENTATION_PLAN_hci_09_information_architecture.md:46-49
Organizations and Teams
In multi-user mode, the Admin UI provides comprehensive management of multi-tenant structures.
| Feature | Description | Relevant Source |
|---|---|---|
| Org CRUD | Create, view, and modify organizations and their slugs. | Sprint Plan:140 |
| Member Management | Search members, change roles via Select component, and handle removals. | Release Checklist:89 |
| Team Scoping | Manage teams within organizations and their specific memberships. | Sprint Plan:143 |
| Billing & Usage | View subscriptions, usage meters, and invoices for enabled organizations. | Release Checklist:92 |
Sources: admin-ui/Release_Checklist.md:86-94, Docs/Design/plans/2026-03-14-phase2-admin-ui-sprint.md:140-145
Data Flow for Administrative Actions
Administrative actions follow a strict validation and guard pattern to prevent unauthorized access.
Maintenance and Operations
The Maintenance page surfaces critical backend operations, including:
- Maintenance Mode: A global toggle that can be enabled with custom messages and an IP allowlist.
- Feature Flags: A management interface to enable or disable system features at runtime without redeploying.
- Incident Management: End-to-end incident handling, from creation and assignment to post-mortem field logging (root cause, action items).
- Data Ops: Management of backups, restoration, and Data Subject Requests (DSR) for compliance.
Sources: admin-ui/Release_Checklist.md:80-84, Docs/Design/plans/2026-03-14-phase2-admin-ui-sprint.md:61-75, Docs/Design/plans/2026-03-14-phase2-admin-ui-sprint.md:162-170
Configuration and Deployment
The Admin UI requires specific environment variables for backend connectivity and authentication.
| Variable | Type | Description |
|---|---|---|
NEXT_PUBLIC_API_URL | String | The base URL of the FastAPI backend. |
SINGLE_USER_API_KEY | String | API key for authentication in single-user mode. |
DATABASE_URL | String | Connection string for the AuthNZ database (PostgreSQL in multi-user). |
UVICORN_WORKERS | Integer | Backend worker count (default 4). |
Sources: admin-ui/Release_Checklist.md:65, Docs/Architecture.md:200-205, Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:32-34
Summary
The Admin UI Dashboard provides a robust, centralized interface for managing the tldw_server ecosystem. By wrapping backend administrative endpoints in a modern React-based UI, it allows for streamlined management of complex systems like multi-tenant organizations, AI resource governance, and automated incident response. Its architecture prioritizes security through administrative guards and provides extensive monitoring via integration with the backend's statistics and evaluation modules.