01 - Entry Points & Execution Flow

NestJS API Bootstrap

File: apps/api/src/main.ts

The API bootstraps a NestJS application with the following configuration:

1. CORS: Enabled for all origins with credentials support; exposes Content-Disposition header for file downloads
2. Security headers: Helmet middleware with custom CSP directives (allows inline styles/scripts for Swagger UI)
3. Body parser limits: 150 MB for both JSON and URL-encoded bodies (supports base64 file uploads)
4. Global validation pipe: ValidationPipe with whitelist, forbidNonWhitelisted, and implicit type conversion
5. API versioning: URI-based versioning (default v1), e.g., /api/v1/tasks
6. Swagger/OpenAPI: Available at /api/docs in development, with API key security scheme and persistent authorization
7. Graceful shutdown: SIGTERM/SIGINT handlers for clean process termination

Registered modules (28 feature modules in apps/api/src/app.module.ts):

Global configuration:

• ConfigModule (global) with AWS and Better Auth config loaders
• ThrottlerModule: 100 requests per 60 seconds per IP (applied as APP_GUARD)

Next.js Frontend Entry

File: apps/app/src/app/page.tsx

The root page is a server component that handles the initial routing decision:

HTTP GET /
  → auth.api.getSession()
    → No session?  → redirect /auth
    → No active org?
      → Pending invite? → redirect /invite/:id
      → Otherwise       → redirect /setup
    → intent=create-additional? → redirect /setup
    → Org not onboarded?       → redirect /onboarding/:orgId
    → User not a member?       → redirect /setup
    → Otherwise                → redirect /:orgId/frameworks

File: apps/app/src/app/layout.tsx

The root layout wraps the application with:

• @trycompai/design-system global CSS
• Providers component (React context: auth session, theme, query client)
• NuqsAdapter for URL search param state management
• Toaster (sonner) for notifications
• Analytics: Vercel Analytics, Dub Analytics (optional), LinkedIn Insight (optional)
• Fonts: GeneralSans (variable), GeistMono

Portal App

Directory: apps/portal/

The portal is a separate Next.js 16 application (port 3002) for external access:

• Employee tasks: Policy acceptance, training completion, device agent installation
• Policy viewer: PDF viewing and digital signature/acceptance
• Organization dashboard: Task progress overview per employee
• Auth: Separate Better Auth instance with magic link and Microsoft OAuth
• API routes: Fleet policy management, device agent download, auth endpoints

Route structure:

/auth                          → Portal authentication
/(app)/(home)/                 → Dashboard and task overview
/(app)/(home)/[orgId]/         → Organization-specific dashboard
/(app)/(home)/[orgId]/policy/[policyId]/ → Policy acceptance view
/api/auth/[...all]             → Better Auth API routes
/api/download-agent/           → Device agent downloads
/api/fleet-policy/             → Fleet policy endpoints

Authentication Flow

File: apps/api/src/auth/hybrid-auth.guard.ts

The HybridAuthGuard implements a dual authentication strategy that supports both external API consumers and the internal frontend:

Incoming request
  │
  ├─ Has X-API-Key header?
  │   → Hash key (SHA256 + optional salt)
  │   → Look up in DB (apiKey table)
  │   → Check expiration
  │   → Set: organizationId, authType='api-key', isApiKey=true
  │   → Roles: null (org-scoped only)
  │
  └─ Has Authorization: Bearer <token>?
      → Validate JWT against Better Auth JWKS endpoint
      → JWKS cached (60s max age, 10s cooldown)
      → On key mismatch: retry with fresh JWKS (0 cache)
      → Require X-Organization-Id header
      → Verify user membership in requested org (DB lookup)
      → Set: userId, userEmail, userRoles, organizationId, authType='jwt'

Additional guards in apps/api/src/auth/:

Auth configuration (apps/app/src/utils/auth.ts):

Better Auth is configured with:

• Prisma adapter (PostgreSQL)
• Plugins: organization, magicLink (1h expiry), emailOTP (6-digit, 10min expiry), jwt (1h expiry), bearer, multiSession, nextCookies
• OAuth providers: Google, GitHub, Microsoft (conditionally enabled via env vars)
• Database hooks: On session creation, auto-sets activeOrganizationId to the user's most recent organization
• Account linking: Enabled for Google, GitHub, Microsoft

Request Lifecycle

A typical authenticated API request flows through:

HTTP Request
  → Express middleware (Helmet, CORS, body parser)
  → ThrottlerGuard (100 req/60s rate limit)
  → HybridAuthGuard (API key or JWT validation)
  → Optional: RequireRoles guard
  → NestJS Controller (route handler)
  → Service layer (business logic)
  → Prisma ORM → PostgreSQL
  → Response serialization → HTTP Response

Trigger.dev Background Jobs

Directory: apps/app/src/trigger/tasks/

Background jobs are defined as Trigger.dev tasks and organized by domain:

API-side tasks (apps/api/src/trigger/questionnaire/):

• answer-question — RAG-based questionnaire answering with vector search
• parse-questionnaire — Questionnaire file parsing and extraction