Overview

The App is the primary Huddle frontend. It’s a Next.js App Router application that talks to the Go backend through a thin, fully type-safe tRPC passthrough layer built on the generated @huddlesurety/api SDK.

Framework: Next.js 16.3.0 (App Router, Cache Components, React Compiler), React 19.2
Language: TypeScript 7 (the native tsgo compiler)
API: tRPC v11 over the @huddlesurety/api SDK
Data: TanStack Query; forms via TanStack Form
UI: Base UI primitives + Tailwind CSS v4
Package manager: Bun — toolchain pinned and tasks run through mise

Project structure

Directorysrc/
- Directoryapp/ App Router — routes grouped by role
  - Directory(pages)/ Authed shell
    Directory(agent)/ Agent-only routes (bonds, contractors, inbox, library)
    …
    Directory(contractor)/ Contractor-only routes (projects, requests)
    …
    Directory(root)/ Root-org routes (overview, agencies, settings)
    …
    Directory(shared)/ Shared routes (requests/new, settings)
    …
  - Directoryapi/ Route handlers — trpc, bond-form export, health
    …
- Directorycomponents/
  - Directoryui/ Base-UI design-system primitives
    …
  - …feature folders bond-form, bond-request, document, project, organization (contractors + surety), …
  - frame.tsx AppFrame — sidebar + top-bar shell
  - providers.tsx tRPC / Query / Theme providers + links
- Directorytrpc/ The passthrough layer (routers, client, server, fetcher)
  - …
- Directoryhooks/ use-*-mutation.ts + a few UI hooks
  - …
- Directorylib/ session.ts (JWT verify), logger, trace, pdf, types
  - …
- Directorystores/ TanStack Store (breadcrumbs)
  - …
- proxy.ts Next middleware — role gating
- pages.ts Nav map keyed by OrgType (drives role gating)
- instrumentation*.ts OpenTelemetry (server) + Faro (browser)