Tech stack

Layer	Choice	Notes
Framework	Next.js 16 (App Router)	Turbopack builds, server components, nested layouts.
UI	React 19	Use cases live in `"use client"` islands.
Styling	Tailwind CSS 4	CSS variables for theme tokens, no PostCSS plugin soup.
Motion	Framer Motion 12 + GSAP 3	Framer for most things, GSAP for timeline-heavy hero moments.
Data	SWR	Stale-while-revalidate caches keyed by backend endpoint.
Icons	lucide-react	Single icon library. Do not add a second one.
Auth	httpOnly cookie	`agnt_token` cookie set by the backend, read by Next.js API routes.

Directory tour

treerepo root

agnt-pwa/
├── public/
│   ├── icon.svg, icon-192.png, icon-512.png
│   ├── manifest.webmanifest
│   └── og-default.png
├── src/
│   ├── app/
│   │   ├── layout.tsx          # Root layout, fonts, JSON-LD
│   │   ├── (public)/           # Marketing, docs, landing, legal
│   │   │   ├── layout.tsx      # Public shell with skip-link + JSON-LD
│   │   │   ├── landing/
│   │   │   ├── docs/           # ← you are here
│   │   │   ├── for-businesses/
│   │   │   ├── for-you/
│   │   │   ├── pricing/
│   │   │   ├── developers/
│   │   │   ├── manifesto/
│   │   │   └── ...
│   │   ├── (authed)/           # Consumer app + venue admin
│   │   │   ├── me/
│   │   │   ├── venue/admin/
│   │   │   └── ...
│   │   └── api/                # 51 route handlers proxying backend
│   ├── components/
│   │   ├── marketing/          # MarketingNav, Footer, AmbientBg
│   │   ├── landing/            # LandingHero, LandingProtocol, ...
│   │   ├── motion/             # Reveal, StaggerGroup, Parallax, CountUp
│   │   ├── trust/              # FAQ, Testimonials, LogoBar, ComparisonMatrix
│   │   ├── docs/               # DocsShell, Sidebar, Pager, Code, Callout
│   │   ├── b2b/                # B2B onboarding flow
│   │   ├── venue-admin/        # Venue owner dashboard
│   │   ├── me/                 # Consumer app
│   │   ├── cards/              # Shareable interaction cards
│   │   └── ui/                 # Button, Badge, Container
│   └── lib/
│       ├── api.ts              # backendFetch, BackendError
│       ├── motion.ts           # Ease, duration, stagger constants
│       ├── stack.ts            # Ecosystem tool registry (data)
│       ├── prompts.ts          # Prompt library (data)
│       └── ecosystem-guides.ts # Integration guides (data)

Route groups

The app is split into three route groups, each with its own layout:

(public) — marketing, legal, landing, manifesto, developer portal, and these docs. Public layout ships the skip-link, the root JSON-LD, and forces dynamic rendering to work around a Next 16 + React 19 SSG edge case.
(authed) — consumer app (/me) and venue admin (/venue/admin). Reads the agnt_token cookie and proxies to the backend for every data fetch.
api — 51 route handlers. Every one is a thin proxy that forwards to the Python backend via backendFetch or authBackendFetch, preserves status codes, and rethrows BackendError.

See Route groups for the full map.

Commands

bashagnt-pwa/

npm install
npm run dev      # http://localhost:3000
npm run build    # production build via Turbopack
npm run lint     # eslint strict

Fonts

Geist Sans for display, JetBrains Mono for labels and stats. Both imported via next/font/google in src/app/layout.tsx and exposed as CSS variables (--font-geist-sans, --font-jetbrains) so CSS-in-JS sites and Tailwind can both reach them.

PWA

Service worker registration lives in src/components/ServiceWorkerRegistration.tsx. The manifest at public/manifest.webmanifest declares icons, theme colour, and the WhatsApp / Telegram launch handlers. iOS-safe-area padding utilities live in globals.css.

Next steps

Route groups— public / authed / api conventions
Design system— tokens, motion primitives, trust components
API layer— backendFetch and error handling

Frontend overview.