Tour

Everything in this scaffold and how to use it.

A guided walkthrough of Augint Example's functions — public site, four authed apps, multi-theme system, Studio surfaces, and customization paths.

What this is — and isn't

It's a scaffold

A starting point you fork and customize.

Every brand string, color, image, and feature toggle is data. Edit config/brand.json, swap the logo, tweak content/*.mdx, and the app reflects your business — without touching components.

It's not a product

Mock data and dev-mode auth ship by default.

MSW intercepts fetches; /login shows a role picker instead of real OAuth. To go live, swap MSW for real APIs and flip NODE_ENV=production — auth automatically uses Cognito. See infrastructure/README.md.

The four authed apps

Each demonstrates a common business-app pattern with realistic mocked data. Click any card to open it — you'll be prompted to pick a role first.

Analytics dashboard

Two internal tabs (Sales, Leads). Sales tab: per-agent stacked leaderboard with By AV / By Deals / Battle modes, agent + recent-deal tables, KPI strip, donut, members-by-carrier, 30-day + 12-month comparison cards, weekly + monthly performance lines, daily volume bars. Leads tab: per-agent disposition stacks, no-sale reasons, daily trends, recent leads. All wired through TanStack Query against MSW; all chart colors track the active theme via CSS variables.

Try this

Switch tabs — URL updates to ?tab=leads but no refetch happens.
Click a date-range pill — handler echoes the range in the response.
Use Battle mode in the leaderboard to see policy-type stacks per agent.
Cycle the theme — every chart's palette updates via var(--chart-1..5).
Click Export CSV — current view's rows download client-side.

Open analytics dashboard

Commissions data entry

react-hook-form + zod validation, sortable + filterable TanStack Table, optimistic updates after submit.

Try this

Add a new commission with the form — table updates immediately.
Filter by status using the "Recent entries" dropdown.
Inspect handler in src/mocks/handlers.ts — POST /api/commissions.

Open commissions data entry

Leads marketplace

Filter sidebar (state + product line), card grid, detail dialog, and a Buy Lead mutation that moves leads to the Purchased tab.

Try this

Filter by state or type using the dropdowns in the header.
Click a card to open the detail dialog, then "Buy Lead".
Switch to the "Purchased" tab to see the moved lead.

Open leads marketplace

Agent quoting tool

Four-step wizard (Customer → Carrier → Coverage → Review) with per-step zod validation and a mock quote computation.

Try this

Walk through all four steps — Next is disabled until the current step validates.
Generate the quote on Review — premium computed from age × coverage in the mock handler.
Hit "New quote" to reset and try a different carrier.

Open agent quoting tool

Multi-theme system

Four palettes, each with light and dark variants. Switching is instant and persists across sessions via cookie.

Available themes

Click the palette icon in any header to cycle. Click sun/moon for variant.

Default

Default brand: deep navy with copper accents — directional and grounded.

data-theme="default"

Neutral

Cool grayscale, professional, restrained — shadcn defaults.

data-theme="neutral"

Woxom

Navy + Tokyo Night neon dashboard. Reference brand-faithful theme.

data-theme="woxom"

Teal Pro

Corporate teal — clean and slightly cool.

data-theme="teal-pro"

Warm Sun

Energetic warm orange — friendly and approachable.

data-theme="warm-sun"

Tokyo

Tokyo Night dark with neon accents; muted indigo when light.

data-theme="tokyo"

Vapor

Pastel lavender light with vibrant accents; deep purple when dark.

data-theme="vapor"

Palette switcher

Top-right of every page header. Cycles the four palettes.

Implemented as a data-theme attribute on <html>. Each theme's CSS file in src/styles/themes/ defines tokens for that selector.

Light / dark toggle

Sun/moon button next to the palette switcher. Toggles class="dark" on <html> via next-themes.

Independent of the palette — switching theme keeps the variant; toggling variant keeps the theme.

Studio — three tweak surfaces under /studio

Non-developer customization without code edits, plus a path to commit drafts as real code.

Theme Studio

Edit any of 21 design tokens live. Drafts apply to the current browser session only — the Copy tokens.css button gives you the CSS to commit.

How to use

1.Pick a palette and variant (light/dark) at the top.
2.Edit any token value — change applies instantly via CSS custom properties.
3.Click Copy tokens.css and paste into src/styles/themes/<theme>.css to make the change permanent.

Open theme studio

Feature flags

Toggle every feature flag declared in config/features.json. Overrides persist in your browser only — defaults still ship to everyone.

How to use

1.Toggle a boolean flag (e.g. authed.showCommissions) — the sidebar nav updates instantly.
2.Use Reset all overrides to restore defaults.
3.Edit config/features.json to change defaults or add new flags. The useFlag() hook reads them.

Open feature flags

Content listing

Browse every MDX content file with its frontmatter. The marketing site renders these via the lib/content.ts abstraction.

How to use

1.Each card maps to a file in content/<slug>.mdx.
2.Edit the file (or ask AI to edit it) and refresh — the public page updates.
3.When you outgrow MDX, swap the impl of getContent() per docs/cms-migration.md.

Open content listing

Auth — dev mode now, Cognito later

Same useSession() everywhere; the provider is the only thing that swaps when you go to production.

Role picker (dev only)

Visit /login to pick a role.

Available roles in dev:

visitorPublic pages and the dashboard shell only.
salesCommissions, the analytics dashboard, run quotes.
agentBuy leads, run quotes.
adminFull access including the Studio surfaces.

Use the Role switcher in the dashboard topbar to switch roles without re-logging-in.

In production, the same login button redirects to Cognito OIDC. The role comes from a Cognito group claim in the JWT.

Code path: src/lib/auth.ts. Branches on NODE_ENV.

Mock data — realistic, mutable, in the browser

MSW intercepts fetches via a service worker. Clicking Buy Lead, submitting a commission, and generating a quote all go through MSW handlers and update in-memory state for the session.

Mutations work

Buy a lead → it moves to Purchased. Add a commission → it appears in the table. Generate a quote → premium is computed from inputs.

Realistic latency

Handlers add a 200-500ms delay so loading states render naturally — you can see optimistic updates working.

Reset on reload

State lives in module memory. Reload the page to reset to seed data in src/mocks/data/.

Customize without writing components

Six file edits cover ~95% of the customization a non-developer needs to do.

Rebrand the whole app

config/brand.json

Name, tagline, contact, social, default theme. The Logo component, header, footer, and every page's hero pull from here.

Drop in your logo

public/logo-placeholder.svg

Single SVG — keep the same dimensions or update the Logo component to size differently.

Author a new theme

src/styles/themes/<your-name>.css

Copy woxom.css, tweak tokens for both [data-theme] and [data-theme].dark, register in src/lib/themes.ts, import in globals.css.

Edit marketing copy

content/*.mdx

Frontmatter for hero/SEO, Markdown body for prose, embed React components inline. The dynamic [slug] route auto-renders any new file.

Add a feature flag

config/features.json

Define key, type (boolean | enum | number | string), default, and description. Use via useFlag(key) in any component.

Add a mock API endpoint

src/mocks/handlers.ts

Add an MSW handler. The handler doubles as the spec for your future Lambda — when you go to prod, this is the contract.

Editing this scaffold with AI

The codebase is shaped so AI assistants (Claude, Cursor, Copilot) can confidently make changes.

Prompts that work well

“Read docs/architecture.md, then add a Newsletter signup section to the home page.”

“Following the patterns in src/components/marketing/, add a Testimonials block to the home page.”

“Generate a deep-purple theme called Twilight. Mirror src/styles/themes/woxom.css and register it in lib/themes.ts.”

Why it works

shadcn/ui components are TSX in your repo — not hidden in node_modules. AI reads and edits them directly.

Theme tokens are CSS variables — one file change updates everything.

AGENTS.md and CLAUDE.md ship with the repo — point AI at them. They cover Next.js 16 gotchas (async params, proxy.ts, no next lint) that will trip up older training data.

Mock handlers are the API spec — when you go to production, AI converts MSW handlers into Lambda implementations line-for-line.

Plumbing the apps don't show

The pieces that make the scaffold cohesive — most invisible day-to-day, all swappable when you need to change them.

Route gating

src/proxy.ts

Auth.js v5 default-exported as the proxy (Next 16 renamed middleware → proxy). Matcher gates /dashboard, /commissions, /leads, /quoting, /studio. Unauthenticated requests redirect to /login.

Topbar role switcher (dev only)

src/components/brand/RoleSwitcher.tsx

Lets you swap visitor / sales / agent / admin without re-logging in. Hidden in prod via the debug.showRoleSwitcher feature flag.

Dynamic MDX route

src/app/(public)/[slug]/page.tsx

Any new file at content/<slug>.mdx is reachable at /<slug>. Frontmatter drives <title>, hero, and SEO. The lib/content.ts abstraction is the swap point for Payload CMS.

Typed fetcher layer

src/lib/api.ts

Thin wrappers around fetch — api.commissions.list(), api.dashboard.get(range), etc. All client code goes through here so MSW (dev) and real APIs (prod) stay interchangeable.

CI, release, pre-commit

.github/workflows/ + .releaserc.json + .husky/

Canonical org pipeline (lint, typecheck, build, audit, semgrep, license-check). semantic-release manages versioning. husky + lint-staged enforce quality on every commit.

Compliance opt-out

.github/.ai-compliance.yaml

Opt-outs for Python-only checks (this is a Node/Next.js repo). Read by the org's compliance dashboard. Edit when you add language-specific tooling.

Reference

Where to look when you want to go deeper.

docs/architecture.md

Why each framework choice was made; the app-data vs. editorial-content split; theme system internals.

docs/cms-migration.md

When and how to swap MDX for Payload CMS as content scales beyond AI editing.

infrastructure/README.md

The CDK/SAM + SST + OpenNext path from local-only scaffold to AWS deploy.

AGENTS.md

Next.js 16 breaking changes, conventions, and AI editing contracts.

CLAUDE.md

Claude-Code-specific recipes for the most common edits.

config/features.json

The 8 boolean flags + enum/number/string flags that drive Augint Example.

Ready to make it yours?

Pick a role and start exploring.

Open the dashboard Try the Theme Studio