National Commerce Docs

Architecture

How the National Commerce web app fits together: stack, structure, and patterns.

This page explains how the code fits together. It helps developers find their way around and follow the team's patterns.

Tech stack

The web app uses these tools:

  • Next.js 15 with the App Router renders pages and runs server code.
  • React 19 and TypeScript build the interface.
  • Supabase stores data in PostgreSQL and signs users in.
  • Cloudflare Workers with Hono run background and edge jobs.
  • Tremor Raw, Radix UI, and Tailwind CSS style the interface.
  • TanStack Query fetches and caches data on the client.
  • React Hook Form and Zod build and validate forms.
  • Biome lints and formats the code.
  • Turborepo with pnpm manages the monorepo.

Monorepo layout

The repo holds several apps and shared packages:

apps/
├── web/          # The Next.js web app (this documentation covers it)
├── worker/       # Cloudflare Worker that builds reports and sends email
├── docs/         # This documentation site (Fumadocs)
├── mcp/          # Model Context Protocol server
└── shipping-audit-tool/

packages/
├── ui/           # Shared UI components
├── supabase/     # Supabase client and generated types
├── emails/       # React Email templates
├── client-config/
└── typescript-config/

Web app structure

The web app splits its code by role:

apps/web/
├── app/          # Pages and API routes (App Router)
├── components/   # Shared components (layout, UI, admin)
├── features/     # Feature modules (the core of the app)
├── lib/          # Shared logic (auth, zones, sku-sync)
├── hooks/        # Shared React hooks
├── utils/        # Supabase client helpers
└── middleware.ts # Protects routes and refreshes sessions

Route groups

The App Router groups routes by access level:

  • app/(auth): the public sign-in page and the auth error page.
  • app/(onboarding): the setup wizard for new users.
  • app/(authenticated): every screen behind sign-in.
  • app/api: server endpoints the front end calls.

Feature modules

Each feature lives in apps/web/features/ and follows one shape:

feature-name/
├── components/   # React components for the feature
├── actions/      # Server Actions that write data
├── hooks/        # Custom React hooks
├── types/        # TypeScript types
└── utilities/    # Helper functions

This layout keeps a feature's code in one place. New work usually starts here.

How data moves

The app fetches and writes data three ways:

  1. Server Components load static or slow-changing data on the server.
  2. TanStack Query with Server Actions loads dynamic data and updates it.
  3. API routes serve the client and handle cron and integration calls.

The Data Flows page shows how data moves between ShipHero, the worker, N8N, and Supabase.

Authentication and access

Supabase Auth signs users in with a 6-digit code sent to their email. There are no passwords. See Sign in to the portal. The middleware.ts file guards routes, refreshes each session, and records the location of each new sign-in from Vercel's edge headers.

Every sign-in and sign-out is recorded in auth_events. That history feeds the Security screen and the emails users get when their account signs in from a new address.

Supabase settings sign-in depends on

These live in the Supabase dashboard, not in the code. Changing them changes how sign-in behaves. The staging project uses the same settings. See Staging and releases.

SettingValueWhy
Magic Link and Confirm signup email templatesBoth send {{ .Token }}Makes Supabase email a code, not a link. Confirmed users get Magic Link, unconfirmed ones (new invitees) get Confirm signup.
Email OTP expiration300 secondsCodes last 5 minutes.
Custom SMTPResend, from noreply@send.nationalcommerce.comSupabase's built-in sender only delivers to the project's own team, at 2 emails an hour.
Rate limit for sending emails1000 per hourProject-wide. Set high so no one can use it up and block everyone's codes.
Session time-box / inactivity timeout7 days / 24 hoursHow long a device stays signed in.
Secure email changeOnChanging an account's email needs confirmation from both inboxes.
Customize Access Token hookreject_password_sign_inRefuses password sign-ins. Removing the password screens alone did not stop direct calls to Supabase.

One access-token hook per project

Supabase allows only one Customize Access Token hook. If you ever need custom claims, add them to reject_password_sign_in instead of replacing it. Turning the hook off in Authentication → Hooks is the quick way to undo it if sign-in ever breaks.

Row-Level Security (RLS) protects every table. Users see only the accounts they may access. On top of that, the app checks each user's role (NC Super Admin, NC Internal User, or Client User) in the middleware, on each page, and in every API route and server action. See Roles and access. A client preview runs through the same checks as a Client User, with every read pinned to the previewed account.

Key patterns

Follow these rules when you build screens:

  • Put MainLayout in each page.tsx, never in layout.tsx.
  • Show skeleton components while data loads. Never print "Loading...".
  • Truncate text with the TruncatedText component.
  • Add type="button" to every button that does not submit a form.
  • Keep dialogs open during async work.

The repo's CLAUDE.md file lists the full set of rules.

On this page