React SPA front-end for the KiberFlow AI platform — conversational RAG, document processing, structured data extraction, longitudinal timelines, FAQ generation, and analytics. This is the UI counterpart of the ira-chat-api backend.
This project is tightly coupled with the ../ira-chat-api backend. All UI specifications and API references live in that repository.
AI agents: start with
UI_INDEX.md— it is the master index with a section cross-reference table linking every spec and topic.
../ira-chat-api/docs/)| Document | Scope |
|---|---|
UI_INDEX.md | Master table of contents — start here |
GLOSSARY.md | Canonical domain names — Detection, not detector/Processor |
UI_MAP.md | Object hierarchy, data-flow diagrams, route structure, navigation map, permissions, Token model, OAuth |
UI_APP_CONFIG.md | Per-screen specs: workspace dashboard, chat, detection, extractor, FAQ, timeline, datasets, dataset/index picker, message grading/tagging |
UI_UX_REQUIREMENTS.md | Cross-cutting standards: design principles, layout system, component specs, notifications, responsive/mobile, accessibility, empty states, file upload, pagination, dark mode, async status, error handling, keyboard shortcuts |
UI_AUTH.md | Authentication flows: login, registration, email confirmation, workspace invitation, password reset, logout, account settings |
UI_ANALYTICS.md | Analytics: metrics dashboard (KPIs, time-series), analysis dashboard (quality, users, categories, tags), grading UI, usage dashboard, export/import |
UI_INTEGRATIONS.md | Integrations: org API keys, webhooks, external apps, OAuth connections, voice (Twilio), messenger bots (Telegram/Slack/WhatsApp), workspace tokens, org domains |
UI_ORG.md | Organization management: general settings, users (invite/edit/remove), org list & switcher, operations dashboard, sidebar navigation, permissions |
BACKEND.md | Planned backend API changes required by the new UI (confirm endpoints, resend, OAuth disconnect, invite acceptance) |
STREAMING_INTEGRATION_RU.md | Centrifuge WebSocket streaming integration details |
| Layer | Technology |
|---|---|
| Framework | React 19 + TypeScript 5.9 |
| Build | Vite 8 (with Tailwind CSS v4 plugin) |
| Styling | Tailwind CSS v4 + motion for animations |
| Components | shadcn/ui (radix-nova style) + Radix UI primitives + Lucide icons |
| Server state | TanStack React Query v5 |
| Routing | React Router v7 (SPA, lazy-loaded routes) |
| Forms | React Hook Form + Zod validation |
| Real-time | Centrifuge (WebSocket for chat streaming) |
| Charts | Recharts |
| Markdown | react-markdown + remark-gfm + react-syntax-highlighter |
src/
├── main.tsx # App entry point
├── App.tsx # Root component (providers, router)
├── router.tsx # Route definitions with lazy loading
├── index.css # Global styles (Tailwind base)
├── queryClient.ts # TanStack Query client config
│
├── auth/ # Route guards (ProtectedRoute, GuestRoute)
├── context/ # React contexts
│ ├── AuthContext.tsx # Session / user state
│ ├── ThemeContext.tsx # Dark/light theme
│ └── WorkspaceContext.tsx # Current workspace state
│
├── hooks/ # Custom hooks
│ ├── useChatSort.ts # Chat list sorting
│ ├── useChatStream.ts # Centrifuge chat streaming
│ ├── useCurrentOrg.ts # Current org from context
│ ├── useDatasetBasePath.ts # Dataset route helpers
│ ├── useIsMobile.ts # Responsive breakpoint
│ ├── useKeyboardShortcuts.ts # Keyboard shortcut handlers
│ ├── useOrgPermissions.ts # Org permission checks
│ ├── usePaginationParams.ts # URL pagination params
│ ├── usePolling.ts # Interval polling for async ops
│ ├── useSortParams.ts # URL sort params
│ ├── useToast.ts # Toast shortcut
│ └── useValidationErrors.ts # Form validation error mapping
│
├── lib/
│ ├── api.ts # Typed fetch wrapper (api.get/post/put/del)
│ ├── constants.ts # Polling intervals, page sizes, storage keys
│ ├── download.ts # File download helpers
│ └── utils.ts # Utility functions
│
├── types/
│ └── api.ts # Shared TypeScript types
│
├── components/
│ ├── ui/ # Reusable UI primitives (Button, Input, DataTable,
│ │ # Pagination, FileUpload, GradeSelector, etc.)
│ ├── layout/ # PageShell, TopBar, Sidebar, Breadcrumb
│ ├── chats/ # Chat-specific shared components
│ ├── datasets/ # Dataset-specific shared components
│ ├── detections/ # Detection-specific shared components
│ ├── extractors/ # Extractor-specific shared components
│ ├── shared/ # Cross-domain shared components
│ ├── topic-router/ # Topic routing utilities
│ └── workspaces/ # Workspace-specific shared components
│
└── pages/ # Page components, organized by domain
├── ErrorPage.tsx # Global error boundary
├── ForbiddenPage.tsx # 403 Forbidden
├── NotFoundPage.tsx # 404 Not Found
├── auth/ # Login, Register, Confirm, Invite, ResetPassword
├── account/ # Account settings
├── org/ # Org settings (general, users, API keys, domains,
│ # webhooks, external apps), org list
├── datasets/ # Dataset list, files, indexes
├── workspaces/ # Workspace list, dashboard
│ └── settings/ # Workspace settings (general, members, tokens,
│ # API keys, categories, voice, messenger, advanced)
├── chats/ # Chat list, messages, settings
├── detections/ # Detection list, items, settings
├── extractors/ # Extractor list, files, results, settings
├── timelines/ # Timeline list, points, settings
├── faqs/ # FAQ list, files, settings
└── analytics/ # Metrics, analysis, usage dashboards
.nvmrc or the Dockerfile)# Install dependencies
npm ci
# Install Playwright's Chromium browser for e2e tests
npx playwright install chromium
# Start dev server (http://localhost:5174)
npm run dev
In development, Vite proxies all /api/v1 requests to the backend. The default target is https://dev.dev-hotline.kibernetika.io.
To proxy to a local backend instead:
cp .env.example .env
# Edit .env and uncomment:
# API_PROXY_TARGET=http://localhost:8083
| Script | Description |
|---|---|
npm run dev | Start Vite dev server with HMR |
npm run build | Type-check + production build |
npm run preview | Preview production build locally (port 5174) |
npm run typecheck | TypeScript type checking (no emit) |
npm run lint | ESLint |
npm run test:e2e | Run the Playwright smoke suite headlessly against a local app server on port 4173 |
npm run test:e2e:headed | Run the Playwright smoke suite in headed mode |
npm run test:e2e:ui | Open the Playwright UI runner |
npm run check:build-assets | Validate build output assets |
Playwright smoke coverage runs the real SPA in Chromium and mocks /api/v1/** traffic inside the browser tests, so the suite does not depend on the default remote Vite proxy target.
# One-time browser install after npm ci
npx playwright install chromium
# Run the smoke suite
npm run test:e2e
Reports are written to playwright-report/ and transient artifacts to test-results/.
On Linux CI or first-time local setup, use npx playwright install --with-deps chromium if the host still needs system browser dependencies.
Multi-stage build: Node 22 (build) → Nginx 1.29 (serve).
# Build image
./build.sh
# Build and push to registry
./build.sh --push
| Env Variable | Effect |
|---|---|
BACKEND_URL | If set, nginx proxies /api/ to this URL (for local Docker / docker-compose). If unset, uses a static nginx config assuming an external ingress handles API routing (Kubernetes). |
IRA_SESSION_ID cookie); all requests go through src/lib/api.ts which handles JSON serialization, error mapping, and automatic logout on 401UI_MAP.md for the full route mapvite.config.ts)@/ resolves to src/The platform organizes features around five workspace app types plus org-level services:
| App | Purpose |
|---|---|
| Chat | Conversational RAG interface with streaming, grading, file attachments, and corrected answers |
| Detection | Document analysis (prescriptions, med lists, etc.) via OCR + LLM |
| Extractor | Structured data extraction driven by JSON Schema |
| Timeline | Longitudinal point-in-time tracking with diff views |
| FAQ | Knowledge-base clustering generated from chat history |
Org-level features: datasets (shared document corpora), analytics (metrics, analysis, usage), integrations (API keys, webhooks, external apps, OAuth, voice, messenger bots), and organization management (users, domains).
Content type
Image
Digest
sha256:5784a5242…
Size
26.6 MB
Last updated
about 9 hours ago
docker pull kuberlab/kiberflow-ui