Documentation

Architecture

UrNammu is built on Next.js 16 with the App Router pattern, using server components by default and client components only where interactivity is required.

High-level architecture

The platform consists of two main components:

  • Main App (Next.js on Vercel) — The dashboard, API routes, and all governance features
  • API Proxy (Azure Functions) — Transparent proxy for Claude and OpenAI API calls that logs usage data

Both components share the same PostgreSQL database.

Tech stack

  • Framework: Next.js 16 (App Router, Turbopack) + TypeScript + React 19
  • Styling: Tailwind CSS 4 + Radix UI primitives + CVA
  • Database: PostgreSQL via Prisma ORM
  • Auth: NextAuth v4 — Google OAuth + Microsoft 365 + Local accounts
  • AI: Provider-agnostic via ai-provider.ts (Anthropic Claude, OpenAI GPT)
  • Charts: Recharts
  • Tables: @tanstack/react-table

App structure

All pages live under src/app/(dashboard)/ with a shared layout that provides the sidebar navigation and top bar. The layout redirects to /login if no session exists.

src/app/
  (auth)/login/         # Login page (public)
  (dashboard)/          # All authenticated pages
    dashboard/          # Command center
    executive/          # Executive posture dashboard
    registry/           # AI system registry (list + detail + edit)
    agents/             # AI agent registry
    risk-center/        # Risk scoring + heat maps + assessments
    compliance/         # Policy management + audit trail
    oversight/          # API usage + cost tracking + vendors
    shadow-ai/          # Shadow AI discovery
    alerts/             # Alert management + exceptions
    settings/           # App configuration
  api/                  # API routes for CRUD + integrations

Data model

The Prisma schema defines 15+ models. Key entities include:

  • AISystem — Core entity for registered AI systems with status, risk level, owner, department, and vendor
  • AIAgent — Autonomous agents linked to parent AI systems with autonomy level and HITL config
  • RiskAssessment — Multi-dimensional risk scores per system
  • Policy — Governance policies with framework mappings
  • DiscoveredTool — Shadow AI discoveries from scans and imports
  • APIUsageLog — Provider API usage telemetry
  • Alert — System alerts with severity levels
  • AuditLog — Full audit trail of all mutations
  • AppSetting — Runtime configuration key-value store

Authentication flow

  1. User visits any dashboard page
  2. Layout checks for session via NextAuth
  3. If no session, redirect to /login
  4. User authenticates via Google OAuth, Microsoft 365, or local credentials
  5. First user to sign in is automatically assigned the ADMIN role
  6. Subsequent users are VIEWER by default (admins can change roles)

API routes are protected by withAuth() and withRole() wrappers that validate session and role before executing the handler.

AI integration

The AI provider is configurable at runtime via Settings. The generateAIResponse(systemPrompt, userPrompt) function in ai-provider.ts abstracts over Anthropic and OpenAI APIs. It reads the configured provider from the AppSetting table and falls back to environment variables.

AI is used for:

  • Risk classification — Automated risk level assessment based on system metadata
  • Compliance gap analysis — Summarizing gaps between system state and policy requirements