Architecture
Overview
The NXTG.AI platform is a Next.js 15 application with TypeScript strict mode, deployed to Vercel. This document covers the system structure, data flows, and key design decisions.
System Overview
The platform is built on the Next.js 15 App Router, which provides React Server Components by default and enables fine-grained control over rendering strategy per route. The monorepo contains the entire application — marketing pages, the Admin Console CMS, interactive demos, and API routes — in a single deployable unit.
App Router with React Server Components, ISR, and Edge Runtime support
Strict mode enabled. All files must pass tsc --noEmit before merge
Utility-first with CSS variables for theming and shadcn/ui integration
Edge Network, automatic ISR revalidation, and Cross-Origin Isolation headers
JWT-based auth middleware protecting /admin/* and /os routes
MDX processing at build time. Input: src/content/. Output: .velite/
Page Architecture
Routes are organized into three categories: public marketing pages, protected application pages, and API routes. All pages use the App Router file convention — a page.tsx file at each route segment.
Public Pages
/ Homepage /products/* Product landing pages (Faultline, Dx3, Podcast Pipeline) /compare/* Comparison pages (Faultline vs competitors) /learn/* Knowledge hub and educational articles /insights/* MDX blog (insights, podcasts, newsletters) /authors/* Author profiles /case-studies/* Enterprise case studies /docs/* Developer documentation (this site) /labs/* Interactive demos catalog /pricing Pricing page /about About page /careers Careers page /contact Contact form /partners Partner directory /customers Customer stories /status Platform status /community Community resources /integrations Integration catalog
Protected Pages
/admin Admin Console dashboard /admin/articles/* Article management (create, edit, delete MDX) /admin/authors/* Author profile management /admin/podcasts/* Podcast episode management /admin/newsletters/* Newsletter archive management /admin/case-studies/* Case study management /admin/settings Admin settings /admin/analytics Analytics dashboard /admin/vitals Core Web Vitals monitoring /os NextGen.OS Playground (WebContainers)
All /admin/* and /os routes require Clerk authentication. Unauthenticated requests are redirected to /sign-in.
API Routes
API endpoints live in src/app/api/ and are deployed as Vercel Serverless Functions. Protected routes validate the Clerk session token on every request.
| Route | Purpose | Auth |
|---|---|---|
/api/admin/* | Admin CMS operations — articles, authors, podcasts, newsletters, case studies | Protected |
/api/analytics/* | Analytics event ingestion and reporting endpoints | Protected |
/api/github | GitHub integration for git-based CMS commit workflow | Protected |
/api/status | Platform health and uptime status endpoint | Public |
/api/waitlist | Waitlist form submission handler | Public |
/api/og | Dynamic Open Graph image generation via @vercel/og | Public |
Content Pipeline
Blog content, articles, and insights use a static MDX pipeline powered by Velite. Content is authored as .mdx files, processed at build time, and imported as typed JavaScript objects by page components. There is no database query at request time for content reads.
Pipeline Flow
Content changes in src/content/ require a production build to take effect. The Admin Console triggers a GitHub commit and Vercel deployment automatically.
Component Hierarchy
Components are organized by function. The root layout wraps all pages with providers. Page-level components are server components by default, with client components used only when interactivity is required.
Layer Structure
RootLayout (src/app/layout.tsx)
ThemeProvider — dark/light mode, CSS variable theming
MotionProvider — Framer Motion LazyMotion config
InvitationModalProvider — global invitation modal state
Navbar — top navigation (server component)
{children} — page content
Footer — site footer
CookieConsent — cookie banner
AnnouncementBanner — global announcement (conditional)
src/components/
ui/ — shadcn/ui primitives + custom design system
admin/ — Admin Console forms and layout
landing/ — Homepage section components
nextgen-os/ — OS overlay components (client-only)
src/design-system/
primitives/ — ScrollReveal, StaggerItem, animation wrappersState Management
Most of the application is stateless — server components render on the server with no client state. Client-side state is used only in interactive features.
Manages OS window state: open/closed windows, positions, dock items, z-order. Located in src/lib/stores/.
ThemeProvider wraps the app for dark/light mode. InvitationModalContext manages the global invitation CTA.
Authentication
Authentication is handled by Clerk. The middleware at src/middleware.ts evaluates every incoming request and applies two functions: route protection and Cross-Origin Isolation headers.
Middleware Responsibilities
Styling System
All styling is done with Tailwind CSS utility classes. CSS variables in src/styles/globals.css define the design token system for light and dark themes. The cn() utility from src/lib/utils.ts merges Tailwind classes with conflict resolution via clsx and tailwind-merge.
- —
background / foreground — page base colors - —
card / card-foreground — card surfaces - —
surface-raised — elevated surfaces (code blocks, sidebars) - —
accent / accent-foreground — brand interaction color - —
muted / muted-foreground — secondary text and icons - —
border — dividers and outlines
shadcn/ui components in src/components/ui/ are built on Radix UI primitives and styled with Tailwind. New components should follow the existing patterns — use CSS variables for colors, Tailwind for layout.
Related Documentation
Have architecture questions?
Open a discussion on GitHub or reach out to the engineering team directly.
Contact Engineering