Component Library

AEGIS uses shadcn/ui as the base component library, extended with custom domain-specific components for compliance dashboards, agent conversations, and knowledge graph visualization.

shadcn/ui Components

The following shadcn/ui primitives are installed in src/components/ui/:

Custom Components

Sidebar (sidebar.tsx)

The collapsible navigation sidebar with:

• Animated width transitions via Framer Motion (240px expanded, 52px collapsed).
• Three navigation entry types: plain items, sections with children, and dividers.
• Active route indicator (animated blue vertical bar using layoutId).
• Collapse state persisted to localStorage.
• Footer with district context and collapse toggle.

Topbar (topbar.tsx)

Top navigation bar featuring:

• Tenant and district display.
• Search button that triggers the command palette (Cmd+K).
• Three-mode density toggle (compact, comfortable, spacious).
• Admin link, user role badge, theme toggle, and sign-out button.
• Uses the useDensity hook from lib/density-context.tsx.

DashboardShell (dashboard-shell.tsx)

Wraps all dashboard page content with:

• DensityProvider — React context providing density and setDensity.
• CommandPalette — global Cmd+K navigation overlay.
• PageTransition — Framer Motion AnimatePresence keyed on the current pathname for smooth page transitions.

DataTable (data-table.tsx)

A feature-rich reusable table component built on TanStack Table:

interface DataTableProps<TData> {
  columns: ColumnDef<TData, any>[];
  data: TData[];
  enableGlobalFilter?: boolean;
  enableColumnVisibility?: boolean;
  enableMultiSort?: boolean;
  enableVirtualization?: boolean;
  onRowClick?: (row: TData) => void;
  loading?: boolean;
  emptyMessage?: string;
  filterPlaceholder?: string;
  className?: string;
  selectedRow?: TData | null;
  getRowId?: (row: TData) => string;
}

Features:

• Multi-column sorting with visual indicators (ArrowUp/ArrowDown icons).
• Global text filter with search input.
• Column visibility toggles (show/hide columns).
• Optional row virtualization via @tanstack/react-virtual for large datasets.
• Row click handlers and selected row highlighting.
• Loading state with skeleton rows.

Used across the compliance matrix, flaring portfolio, entity explorer, and events list.

Sparkline (sparkline.tsx)

Inline micro-charts using Recharts LineChart:

interface SparklineProps {
  data: number[];       // Array of values
  width?: number;       // Default: 80
  height?: number;      // Default: 24
  color?: string;       // Default: "#3b82f6"
  showDot?: boolean;    // Default: true
}

Used in the flaring portfolio table to show volume trends inline with each row.

CommandPalette (command-palette.tsx)

Global navigation overlay powered by cmdk:

• Opens with Cmd+K (or Ctrl+K) and closes with Escape.
• Provides quick navigation to all major pages: Conversations, Filing Review, Compliance, Flaring, Entity Explorer.
• Renders as a full-screen overlay with search input and filtered results.

PageTransition (page-transition.tsx)

Framer Motion wrapper for route transitions:

• Uses AnimatePresence with mode="wait" for clean enter/exit animations.
• Keyed on the current pathname so each page gets its own animation lifecycle.

ThemeToggle (theme-toggle.tsx)

Dark/light mode toggle button in the topbar that cycles through next-themes values.

Compliance Components

Located in src/components/compliance/:

Conversation Components

Located in src/components/conversations/:

Data Visualization

Recharts

Recharts is used across all dashboard pages for charts:

• BarChart: Monthly flaring volume vs. permitted limits, deadline distributions.
• LineChart: Compliance trends over time, production sparklines.
• Donut/Pie: Filing status distribution.
• ResponsiveContainer: All charts are responsive to container width.

Shared chart configuration is provided by lib/chart-utils.ts:

• ChartTooltip — custom tooltip component with consistent styling.
• ChartGradientDefs — SVG gradient definitions for bar fills.
• chartGridProps — shared grid line styling.
• chartAxisProps — shared axis tick styling and formatting.

Cytoscape.js

The knowledge graph explorer and entity relationship views use Cytoscape.js (cytoscape + react-cytoscapejs):

• Graph layout uses the dagre algorithm via cytoscape-dagre.
• Entity nodes are color-coded by type.
• Edges represent relationships (OPERATED_BY, LOCATED_IN, etc.).
• Interactive: pan, zoom, click-to-select nodes.

Status Color System

The lib/status-colors.ts module provides centralized color mappings:

// Compliance status colors
complianceColors: {
  compliant: "bg-green-...",
  action_needed: "bg-amber-...",
  overdue: "bg-red-...",
  in_review: "bg-blue-...",
  not_applicable: "bg-neutral-...",
}
 
// Severity colors
severityColors: {
  critical: "...",
  warning: "...",
  info: "...",
}

The getBadgeColor(colorMap, status) helper returns the appropriate Tailwind class string for any status value, with fallback to neutral styling for unknown statuses.

Icon System

Icons come from Lucide React (lucide-react). Entity types have dedicated icon mappings in lib/entity-icons.ts for use in the sidebar, entity explorer, and compliance matrix.

Common icons used:

• ShieldCheck — compliance
• ClipboardList — filings
• Flame — flaring
• CalendarClock — events/deadlines
• MessageSquare — conversations
• Landmark — entities
• RefreshCw — refresh actions
• Search — search inputs