Skip to main content

Webapp Architecture

The webapp is a Next.js 14 App Router application located at apps/webapp/. It serves all of the CleverThis UI: Dashboard, Library, Namespaces, Deployments, Chat, Usage & Billing, and Settings pages.

The webapp acts as a Backend-for-Frontend (BFF): route handlers in app/api/ proxy requests to the Python API server, attaching session credentials on behalf of the browser. Browser code never holds raw API keys — only the BFF session does.

Directory structure​

apps/webapp/
├── app/
│   ├── (auth)/          # Sign-in, sign-up, verify-email pages
│   ├── (dashboard)/     # All authenticated app pages
│   │   ├── dashboard/
│   │   ├── library/
│   │   ├── namespaces/
│   │   ├── deployments/
│   │   ├── chat/
│   │   └── settings/
│   └── api/             # Next.js route handlers (BFF layer)
├── components/          # Shared UI components (shadcn/ui based)
├── lib/
│   └── a2a-client.ts    # TypeScript client for the A2A control plane
└── public/

A2A client pattern​

The A2A client (lib/a2a-client.ts) is a typed TypeScript wrapper around the JSON-RPC A2A control plane. Server Components and route handlers import it to make management calls. It reads the management key from environment variables — it is never exposed to the browser.

The A2A client is strongly typed: each method has TypeScript interfaces for params and return values generated from the A2A method schema.

Authentication​

Authentication is handled by NextAuth.js. It supports email/password credentials and OAuth providers (Google, GitHub). Sessions are stored server-side (database sessions). The session object is available in Server Components via getServerSession().

Coming soon

Detailed state management notes (React Query usage, optimistic updates) and component library conventions are being added.