Frontend Overview

The AEGIS frontend is a Next.js application that provides the dashboard UI for regulatory compliance management. It connects to the backend services through the API Gateway on port 8000.

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 API client with JWT
│   │   ├── api-urls.ts        # Service URL configuration
│   │   ├── 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

The frontend connects to backend services via a centralized URL configuration in src/lib/api-urls.ts:


export const API_URLS = {
  gateway: process.env.NEXT_PUBLIC_API_URL || "http://localhost:8000",
  orchestration: process.env.NEXT_PUBLIC_ORCH_URL || "http://localhost:8001",
  memory: process.env.NEXT_PUBLIC_MEMORY_URL || "http://localhost:8002",
  knowledgeGraph: process.env.NEXT_PUBLIC_KG_URL || "http://localhost:8003",
  approval: process.env.NEXT_PUBLIC_APPROVAL_URL || "http://localhost:8004",
  compliance: process.env.NEXT_PUBLIC_COMPLIANCE_URL || "http://localhost:8006",
  flaring: process.env.NEXT_PUBLIC_FLARING_URL || "http://localhost:8007",
} as const;

In production, all traffic should route through the API Gateway on port 8000. In local development, some pages connect directly to specific services for convenience (for example, the filing review page talks directly to the approval service on port 8004).

The centralized API client in src/lib/api.ts automatically attaches JWT bearer tokens from the aegis_token cookie to every request. 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.