Architecture

Project Structure

coordinator-web/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes (logging endpoint)
│   ├── portal/            # Authenticated portal routes
│   ├── profile/           # User profile routes
│   └── (marketing)/       # Public marketing pages
├── components/            # Reusable UI components
│   ├── ui/               # Base primitives (shadcn/Radix)
│   ├── forms/            # Form components by domain
│   ├── tables/           # Data table components
│   ├── cards/            # Card components
│   ├── layout/           # Layout components
│   ├── modal/            # Modal dialogs
│   ├── stream/           # Video streaming components
│   └── upload/           # File upload components
├── context/              # React context providers
├── hooks/                # Custom React hooks
│   ├── embeddings/       # Embedding-related hooks
│   ├── sessions/         # Session-related hooks
│   └── trainings/        # Training-related hooks
├── lib/                  # Shared utilities
│   ├── auth-client.ts    # BetterAuth client
│   ├── logger.ts         # Server-side Winston logger
│   ├── logger-client.ts  # Client-side logger
│   ├── stripe.ts         # Stripe client
│   ├── tutorial.ts       # Tutorial system
│   └── utils.ts          # Common utilities
├── types/                # TypeScript type definitions
├── public/               # Static assets
└── docs/                 # This documentation

Routing Architecture

Public Routes

Route	Purpose
/	Home/landing page
/about	About page
/pricing	Pricing information
/contact	Contact form
/login	Sign in
/sign-up	Registration
/reset-password	Password recovery

Profile Routes (Authenticated)

Route	Purpose
/profile	User dashboard
/profile/settings	Personal settings
/profile/organizations	Organization list
/profile/organizations/create	Create new org
/profile/invites	Pending invitations
/profile/teams	Teams membership

Portal Routes (Authenticated + Organization Scoped)

Base path: /portal/[organizationSlug]

Route	Purpose
/	Organization landing
/pay	Billing checkout
/pay/success	Checkout confirmation
/accept-invite/[inviteID]	Accept org invite
/settings/members	Organization members
/settings/teams	Organization teams
/settings/billing	Billing management

Team-Scoped Routes

Base path: /portal/[organizationSlug]/[teamID]

Route	Purpose
/	Team landing
/chat	Chat home
/chat/[chatID]	Specific conversation
/sessions	Sessions overview
/sessions/manage	Session list
/sessions/new	Create session
/sessions/forms	Form templates
/sessions/[sessionID]	Session detail
/context	Context overview
/context/upload	Upload files
/context/manage	Manage embeddings
/training	Training overview
/training/new	Create training job
/training/jobs	Job list
/settings/team	Team settings

Architectural Patterns

Provider Hierarchy

<TanstackProvider>          {/* TanStack Query client */}
  <ConditionalLayout>        {/* Marketing vs Portal layout */}
    <RoleProvider>           {/* RBAC enforcement */}
      {children}
    </RoleProvider>
  </ConditionalLayout>
</TanstackProvider>

Data Flow

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Component     │────▶│   Custom Hook    │────▶│   TanStack      │
│                 │     │   (useSession)   │     │   Query         │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                │                        │
                                ▼                        ▼
                        ┌──────────────────┐     ┌─────────────────┐
                        │   fetchJSON()    │────▶│   REST API      │
                        │   + Auth Token   │     │                 │
                        └──────────────────┘     └─────────────────┘

Authentication Flow

┌─────────────────┐
│   middleware    │  Route protection via proxy.ts
│   (proxy.ts)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   BetterAuth    │  Session verification
│   get-session   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   authClient    │  React client for auth state
│   useSession()  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   useAuth()     │  JWT token + active org sync
│                 │
└─────────────────┘

Key Files

Configuration

File	Purpose
next.config.ts	Next.js configuration, external packages
tsconfig.json	TypeScript configuration
components.json	shadcn/ui configuration
eslint.config.mjs	ESLint configuration
postcss.config.mjs	PostCSS/Tailwind configuration

Entry Points

File	Purpose
app/layout.tsx	Root layout with providers
proxy.ts	Auth middleware
lib/auth-client.ts	BetterAuth client initialization

Core Utilities

File	Purpose
lib/utils.ts	fetchJSON, cn, formatting helpers
lib/logger.ts	Winston server logger
lib/logger-client.ts	Client-side logger
lib/tutorial.ts	Tutorial step management