EKA Frontend

Engineering Knowledge Assistant — AI-powered chat, code search, and analytics dashboard.

A Next.js (App Router) single-page application that provides an intelligent engineering assistant interface. Connects to the EKA backend for LLM-powered chat, code search, graph visualization, and ingestion management.

Quick start

cp .env.example .env.local
npm install
npm run dev

Opens at http://localhost:3000. Requires the EKA backend on http://localhost:8080.

---

Routes

Route	Feature	File
/login	Auth — email/password or OAuth2 (Google/GitHub)	src/features/auth/
/oauth2/callback	OAuth2 token exchange handler	src/app/(auth)/oauth2/callback/
/chat	LLM-powered chat with streaming, citations, conversation history	src/features/chat/
/search	Semantic + hybrid code search across indexed repos	src/features/search/
/sources	Manage ingestion sources (GitHub, GitLab, Confluence, web)	src/features/sources/
/ingestion	Ingestion pipeline status, retry, and history	src/features/ingestion/
/graph	Interactive Neo4j knowledge graph browser (React Flow)	src/features/graph/
/analytics	Usage metrics, top queries, embedding stats	src/features/analytics/
/observability	System health, trace sampling, error rates	src/features/observability/
/admin	User management, role assignment (ADMIN only)	src/features/admin/
/settings	Profile, API keys, preferences	src/features/settings/
/	Dashboard — stats overview	src/app/(dashboard)/page.tsx

Architecture

src/
├── app/                  # Next.js App Router pages + layouts
│   ├── (auth)/           #    Login + OAuth2 callback (public)
│   └── (dashboard)/      #    All authenticated routes (sidebar shell)
├── components/
│   ├── layout/           #    Sidebar, shell layouts
│   ├── shared/           #    AuthProvider, DataTable, ErrorBoundary, etc.
│   └── ui/               #    Radix UI primitives (button, dialog, input, tabs…)
├── features/             #    Feature-sliced modules (one per route)
│   ├── chat/             #      Chat page, SSE streaming, conversation context
│   ├── search/           #      Hybrid search UI, history, saved queries
│   ├── sources/          #      Source CRUD, connectors, status streaming
│   ├── analytics/        #      Charts (Recharts), stat cards, heatmaps
│   ├── graph/            #      React Flow knowledge graph
│   ├── ingestion/        #      Pipeline monitoring
│   ├── observability/    #      System health dashboards
│   ├── admin/            #      User roles and management
│   └── settings/         #      Profile and preferences
├── hooks/                #    Shared React hooks + TanStack Query wrappers
├── lib/                  #    HTTP client, env, error factory, formatters
├── services/             #    API service layer (auth, sources, admin)
├── store/                #    Zustand stores (auth, chat)
├── styles/               #    Global CSS, Tailwind v4
└── types/                #    TypeScript type definitions

Key patterns

Authentication

The app supports two auth flows:

1. Email + password — POST /api/v1/auth/login returns a JWT stored in Zustand persist (localStorage).
2. OAuth2 (Google/GitHub) — redirects to backend OAuth2 endpoint; callback delivers JWT via query param.

Token is managed by Zustand persist middleware (src/store/auth-store.ts). The HTTP client interceptor (src/lib/http-client.ts) attaches the Authorization: Bearer header to every request and redirects to /login on 401.

SSE streaming

Chat and AI feature endpoints use Server-Sent Events. The createSSEStream() function in src/lib/http-client.ts handles chunked data: lines with proper buffer reassembly when a chunk boundary splits a line:

const { done, value } = await reader.read();
buffer += decoder.decode(value, { stream: true });
const parts = buffer.split('\n\n');
buffer = parts.pop() ?? '';  // keep incomplete trailing segment

TanStack Query

All API queries use TanStack Query via centralized query keys (src/lib/query-keys.ts) and auto-generated hooks in src/hooks/api/. Polling, caching, and optimistic updates follow the pattern established in each feature's api/ directory.

UI components

Components use Radix UI primitives styled with Tailwind CSS v4 + class-variance-authority. Light/dark theme switching via next-themes with system preference detection.

Environment variables

Variable	Default	Required	Description
NEXT_PUBLIC_API_URL	http://localhost:8080	Yes	Backend API base URL
NEXT_PUBLIC_WS_URL	(API_URL)	No	WebSocket endpoint
NEXT_PUBLIC_AUTH_DOMAIN	—	No	OAuth2 domain
NEXT_PUBLIC_AUTH_CLIENT_ID	—	No	OAuth2 client ID

Scripts

Command	Description
npm run dev	Start dev server with Turbopack
npm run build	Production build
npm run start	Start production server
npm run lint	Run ESLint

Tech stack

Layer	Technology
Framework	Next.js 16.2 (App Router)
Language	TypeScript 5, React 19
Styling	Tailwind CSS v4, Radix UI primitives
State	Zustand 5 (client state), TanStack Query 5 (server state)
Charts	Recharts, Custom sparklines
Graph	React Flow (@xyflow/react)
Markdown	react-markdown, rehype-katex, remark-gfm
HTTP	Axios with retry + refresh interceptor
Fonts	Inter, Instrument Sans, JetBrains Mono

Accessibility

• Skip-to-content link on route load
• aria-live="polite" on streaming LLM responses for screen readers
• All hover-reveal actions use group-focus-within:opacity-100 for keyboard navigation
• Sort buttons in data tables include explicit type="button"
• Focus-visible ring styles throughout