Frontend Overview

The AEGIS frontend is a Next.js 16 (App Router) application that provides the dashboard UI for the AEGIS compliance runtime — a domain-neutral platform whose first installed vertical is Texas RRC oil & gas. It talks to the backend same-origin through the API Gateway: browser calls go to /api/v1/* (Caddy routes them to the Go gateway on the box; a next.config.ts rewrite proxies them to localhost:8000 in dev). Session auth rides the httpOnly aegis_token cookie, so the browser attaches it automatically and no token is exposed to JavaScript (R42b/c).

Tech Stack

Technology	Version	Purpose
Next.js	16.1.7	React framework (App Router)
React	19.2.3	UI library
TypeScript	5.x	Type-safe JavaScript
Tailwind CSS	4.x	Utility-first CSS framework
shadcn/ui	4.x	Component library (Radix-based)
Recharts	3.8.x	Data visualization and charts
Framer Motion	12.x	Animation library
TanStack Table	8.x	Data table with sorting/filtering/virtualization
TanStack Virtual	3.x	Virtualized list rendering
Cytoscape.js	3.x	Knowledge graph visualization
cmdk	1.x	Command palette (Cmd+K)
Lucide React	0.577.x	Icon library
sonner	2.x	Toast notifications
next-themes	0.4.x	Dark/light theme support
@dnd-kit	6.x/10.x	Drag and drop

Folder Structure


frontend/
├── next.config.ts             # Next.js configuration
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── postcss.config.mjs         # PostCSS with Tailwind
├── src/
│   ├── app/                   # App Router pages
│   │   ├── layout.tsx         # Root layout (AuthProvider, ThemeProvider)
│   │   ├── page.tsx           # Redirects to /compliance
│   │   ├── globals.css        # Global styles
│   │   ├── login/             # Login page
│   │   └── (dashboard)/       # Dashboard route group
│   │       ├── layout.tsx     # Sidebar + Topbar wrapper
│   │       ├── compliance/    # Compliance dashboard + workspace
│   │       ├── filings/       # Filing review queue
│   │       ├── flaring/       # Flaring dashboard
│   │       ├── events/        # Events timeline
│   │       ├── conversations/ # Agent chat with SSE streaming
│   │       ├── entity/        # Entity explorer
│   │       └── configuration/ # Entity types, relationship types, event types
│   ├── components/
│   │   ├── sidebar.tsx        # Navigation sidebar (collapsible)
│   │   ├── topbar.tsx         # Top navigation bar
│   │   ├── data-table.tsx     # Reusable TanStack data table
│   │   ├── sparkline.tsx      # Inline sparkline charts
│   │   ├── dashboard-shell.tsx# DensityProvider + CommandPalette + PageTransition
│   │   ├── command-palette.tsx# Cmd+K navigation
│   │   ├── theme-provider.tsx # next-themes wrapper
│   │   ├── theme-toggle.tsx   # Dark/light mode toggle
│   │   ├── page-transition.tsx# Framer Motion page transitions
│   │   ├── alert-badge.tsx    # Alert indicator badge
│   │   ├── motion-button.tsx  # Animated button
│   │   ├── compliance/        # Compliance-specific components
│   │   ├── conversations/     # Conversation-specific components
│   │   ├── workspace/         # Entity workspace components
│   │   ├── events/            # Events-specific components
│   │   └── ui/                # shadcn/ui primitives
│   ├── lib/
│   │   ├── api.ts             # Centralized same-origin API client (cookie auth)
│   │   ├── api-admin-users.ts # Admin Users & Roles client (/api/v1/auth/admin/*)
│   │   ├── api-settings.ts    # Platform Settings client
│   │   ├── conversations/     # Conversation data layer (TurnStream, store, parsers)
│   │   ├── graph/             # Cytoscape element builders + node styles
│   │   ├── auth-context.tsx   # AuthProvider (React context)
│   │   ├── density-context.tsx# UI density provider (compact/comfortable/spacious)
│   │   ├── utils.ts           # Utility functions (cn, etc.)
│   │   ├── status-colors.ts   # Status color mappings
│   │   ├── chart-utils.ts     # Shared Recharts configuration
│   │   └── entity-icons.ts   # Entity type icon mappings
│   └── middleware.ts          # Auth middleware (cookie check)

API Gateway Connection

Every frontend network call is same-origin to /api/v1/* and routes through the authenticated Go gateway (R42b/c). There is no per-service URL configuration anymore — the old src/lib/api-urls.ts helper and all NEXT_PUBLIC_*_URL env vars were deleted. The gateway maps each /api/v1/* path to the right backend (e.g. /api/v1/entities → knowledge-graph-service, /api/v1/execute → orchestration-engine).

On the box, Caddy routes /api/v1/* to the Go gateway before Next.js sees the request.
In dev, a next.config.ts rewrite proxies /api/v1/* to GATEWAY_INTERNAL_URL (default http://localhost:8000), making dev same-origin exactly like the box.

Because requests are same-origin, the browser attaches the httpOnly aegis_token cookie automatically — src/lib/api.ts constructs no Authorization header and never reads the cookie (it is not JS-readable). See the API Client page for details.

Running the Frontend

Development


cd frontend
npm install
npm run dev

The dev server starts on http://localhost:3000.

The default dev login is admin@aegis.local / aegis-dev-admin. Enter these on the login page to authenticate locally.

Design Principles

Dark theme by default — enterprise SaaS look with data-dense, understated, trustworthy design. Visual benchmark is Enverus / DrillingInfo.
Three density modes — compact, comfortable, spacious. Controlled via the topbar toggle and persisted to localStorage.
Animated transitions — Framer Motion page transitions and sidebar collapse/expand animations.
Command palette — Cmd+K (or Ctrl+K) opens a global navigation palette powered by cmdk.
Compliance-first navigation — the root path (/) redirects to /compliance, making the compliance dashboard the default landing page.

Key Dependencies

The frontend does not use react-force-graph-2d for graph visualization. Instead, it uses Cytoscape.js (cytoscape + react-cytoscapejs + cytoscape-dagre) for the knowledge graph explorer and entity relationship views.

Chart rendering uses Recharts with shared configuration from lib/chart-utils.ts for consistent styling across all dashboard pages (gradients, tooltips, axis formatting, grid lines).

The TanStack Table integration (@tanstack/react-table) provides the core DataTable component used across the compliance matrix, flaring portfolio, entity explorer, and events list. It supports multi-column sorting, global filtering, column visibility toggles, and optional row virtualization via @tanstack/react-virtual.