WebArchitecture

App Architecture

The Quper web application is built on Next.js 16 App Router. The routing hierarchy maps directly to feature modules, with each module having its own layout, data-fetching layer, and component tree.

Folder Structure

src/app/ — Route Tree

src/app/
├── layout.tsx               → Root layout (ThemeProvider, Auth0 session)
├── (auth)/                  → Auth-required route group (middleware protected)
│   ├── dashboard/           → Main FinOps dashboard overview
│   ├── cost-and-usage/      → FinOps analytics module
│   │   ├── page.tsx         → Overview with cost trend charts
│   │   ├── unit-cost/       → Unit cost analysis (summary + time-series)
│   │   └── optimization/    → Optimization indicators and anomaly views
│   ├── redshift/            → Redshift health module
│   │   ├── page.tsx         → Cluster overview
│   │   ├── table-analysis/  → Table metrics and vacuum health
│   │   ├── query-analysis/  → Slow and spilling queries
│   │   ├── alerts/          → Alert event log and management
│   │   └── observe/         → Live cluster observation
│   ├── iam/                 → Identity & access management
│   │   ├── users/           → User management table and modals
│   │   ├── groups/          → Group management
│   │   └── roles/           → Role and permission management
│   ├── monitoring/          → Alerts and escalation
│   │   ├── alert-rules/     → Rule configuration
│   │   ├── escalation/      → Escalation policy builder
│   │   └── notifications/   → Notification channel setup
│   └── vidura/              → AI chat interface
│       └── page.tsx         → Full-page chat with session sidebar
└── api/                     → API route handlers (Next.js → FastAPI proxy)
    └── vidura/
        └── route.ts         → Proxy: POST /api/vidura → FastAPI /ask

Key Architectural Decisions

Module Isolation

Each feature module (cost-and-usage, redshift, iam, monitoring, vidura) has its own nested layout component. This means each module can independently define its sidebar, header state, and data prefetch without affecting other modules.

Server Components for Data Fetching

By default, all page and layout components are React Server Components (RSC). They fetch data directly on the server using the authenticated user's session token, then pass the pre-fetched data as props to client components. This eliminates loading skeletons for the initial render of most pages.

Client Components for Interactive UI

Only components that require browser APIs or user interaction are marked with 'use client':

Recharts chart components (require DOM measurement)
Form modals with controlled inputs
The Vidura chat message thread (streaming updates)
The "Ask Vidura" floating button and drawer

API Routes as Backend Proxy

The Next.js api/ directory contains thin proxy route handlers that forward requests from the browser to the FastAPI backend. This pattern:

Keeps the FastAPI backend URL private from the browser
Allows the Next.js middleware to validate auth before proxying
Enables edge-level caching for read-heavy endpoints

Auth0 Middleware Route Protection

middleware.ts — Route Protection

import { withMiddlewareAuthRequired } from "@auth0/nextjs-auth0/edge";

export default withMiddlewareAuthRequired();

export const config = {
  matcher: ["/(auth)/:path*", "/api/vidura/:path*"],
};

Route Groups

The (auth) route group uses parentheses notation — this is a Next.js App Router convention that groups routes under shared middleware without adding a URL segment. All routes inside (auth)/ are protected by Auth0 middleware; the URL remains /dashboard, not /auth/dashboard.