Key Files Map

Tier 1: Start Here (Must-Read to Understand the System)

File	Responsibility
`apps/api/src/main.ts`	API entry point: CORS, security headers, body parsing, Swagger, versioning
`apps/api/src/app.module.ts`	Root module: imports all 42 feature modules
`apps/api/src/auth/hybrid-auth.guard.ts`	Core auth: 3-method authentication (API Key → Service Token → Session)
`apps/api/src/auth/permission.guard.ts`	Core RBAC: permission enforcement for every endpoint
`packages/auth/src/permissions.ts`	RBAC source of truth: all resources, actions, and built-in roles
`packages/db/prisma/schema/` (directory)	Data model: 45 Prisma files defining every entity
`apps/app/src/app/(app)/[orgId]/layout.tsx`	Frontend auth gate: org validation, permission resolution, feature flags
`CLAUDE.md`	Project rules: conventions, architecture decisions, do/don't patterns

Tier 2: Core Infrastructure

Authentication & Authorization

File	Responsibility
`apps/api/src/auth/auth.server.ts`	Better Auth server config: social providers, cookies, custom domains
`apps/api/src/auth/auth.module.ts`	Auth module: exports guards, API key service
`apps/api/src/auth/service-token.config.ts`	Service token definitions (trigger, portal, trust)
`apps/api/src/auth/api-key.service.ts`	API key generation, hashing, prefix-indexed validation
`apps/api/src/auth/auth-context.decorator.ts`	Parameter decorators: @OrganizationId, @UserId, @MemberId
`apps/api/src/auth/require-permission.decorator.ts`	@RequirePermission metadata setter
`apps/api/src/auth/types.ts`	AuthenticatedRequest and AuthContext interfaces
`apps/app/src/utils/auth.ts`	Server-side auth client (getSession, hasPermission, etc.)
`apps/app/src/utils/auth-client.ts`	Client-side auth (signIn, signOut, useSession)
`apps/app/src/lib/permissions.server.ts`	Permission resolution (built-in + custom roles)
`apps/app/src/lib/permissions.ts`	Frontend permission checks (hasPermission, canAccessRoute)

Audit & Compliance

File	Responsibility
`apps/api/src/audit/audit-log.interceptor.ts`	Auto audit logging: captures mutations with before/after diffs
`apps/api/src/audit/audit-log.controller.ts`	Audit log query API
`apps/api/src/roles/roles.service.ts`	Permission validation, privilege escalation prevention

Data Access

File	Responsibility
`apps/app/src/lib/api-client.ts`	Client-side API client (credentials: include, org header)
`apps/app/src/lib/api-server.ts`	Server-side API client (forwards cookies, no-store cache)
`packages/db/prisma/schema.prisma`	Prisma generator + datasource config

Tier 3: AI & LLM Systems

RAG & Embeddings

File	Responsibility
`apps/api/src/vector-store/lib/core/generate-embedding.ts`	Embedding generation (text-embedding-3-small)
`apps/api/src/vector-store/lib/core/similarity-search.ts`	Vector similarity search (pgvector)
`apps/api/src/vector-store/lib/sync/`	Organization-wide + per-document vector sync

Questionnaire AI

File	Responsibility
`apps/api/src/questionnaire/utils/content-extractor.ts`	Multi-format file extraction (~1092 lines)
`apps/api/src/questionnaire/utils/question-parser.ts`	AI-powered Q&A extraction from documents
`apps/api/src/questionnaire/utils/constants.ts`	System prompts for RAG answering
`apps/api/src/trigger/questionnaire/answer-question-helpers.ts`	RAG answer generation (batch + single)

Policy AI

File	Responsibility
`apps/app/src/app/api/policies/[policyId]/chat/route.ts`	Streaming policy chat (Claude Sonnet)
`apps/app/src/app/api/policies/[policyId]/edit-section/route.ts`	Single-turn section editor
`apps/app/src/app/(app)/[orgId]/policies/[policyId]/editor/tools/policy-tools.ts`	AI tools for policy context
`apps/api/src/trigger/policies/update-policy-helpers.ts`	Policy generation (GPT-5-mini)

Cloud Security AI

File	Responsibility
`apps/api/src/cloud-security/ai-remediation.service.ts`	2-phase AI fix planning (Claude Opus, temp 0)
`apps/api/src/cloud-security/ai-remediation.prompt.ts`	AWS fix plan schema + prompts
`apps/api/src/cloud-security/gcp-ai-remediation.prompt.ts`	GCP REST API fix schemas
`apps/api/src/cloud-security/azure-ai-remediation.prompt.ts`	Azure ARM API fix schemas
`apps/api/src/cloud-security/aws-command-executor.ts`	AWS SDK command execution from AI output

Assistant & Automation

File	Responsibility
`apps/api/src/assistant-chat/assistant-chat.controller.ts`	General assistant chat endpoint (GPT-5)
`apps/api/src/assistant-chat/assistant-chat-tools.ts`	Permission-gated AI tools
`apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automation/[automationId]/chat.tsx`	Task automation chat UI

Tier 4: Integration Platform

File	Responsibility
`packages/integration-platform/src/types.ts`	Integration manifest types (~891 lines): auth, checks, webhooks
`packages/integration-platform/src/registry/index.ts`	Integration registry (code + dynamic manifests)
`packages/integration-platform/src/runtime/check-context.ts`	Check execution context (~538 lines): auto-auth, pagination, results
`packages/integration-platform/src/dsl/interpreter.ts`	DSL → executable check interpreter
`packages/integration-platform/src/dsl/expression-evaluator.ts`	Expression evaluation (16 operators)
`packages/integration-platform/src/task-mappings.ts`	75 framework-aligned task templates
`apps/api/src/cloud-security/cloud-security.service.ts`	Cloud security scan orchestration (~702 lines)
`apps/api/src/integration-platform/controllers/webhook.controller.ts`	HMAC-verified webhook handler

Tier 5: Background Jobs (Trigger.dev)

File	Responsibility
`apps/api/trigger.config.ts`	API Trigger.dev project config
`apps/app/trigger.config.ts`	App Trigger.dev project config
`apps/api/src/trigger/cloud-security/`	Cloud security scan tasks (15 min timeout)
`apps/api/src/trigger/vendor/vendor-risk-assessment-task.ts`	AI vendor assessment (Firecrawl + GPT-5.2)
`apps/api/src/trigger/vector-store/`	Vector store processing tasks
`apps/app/src/trigger/tasks/cloud-security/`	Remediation tasks (preview, single, batch)
`apps/app/src/trigger/tasks/auditor/generate-auditor-content.ts`	AI auditor content (GPT-5.2)

Tier 6: Frontend Patterns

File	Responsibility
`apps/app/src/app/layout.tsx`	Root layout: session, providers, analytics
`apps/app/src/proxy.ts`	Middleware: session cookie check, auth redirect
`apps/app/src/app/page.tsx`	Root page: org redirect, onboarding check
`apps/app/src/app/providers.tsx`	React Query + Theme + GTM + Analytics providers
`apps/app/src/env.mjs`	Environment variable validation (57 server + 12 client)
`apps/app/src/app/(app)/onboarding/`	Multi-step onboarding wizard

Tier 7: Supporting Infrastructure

File	Responsibility
`apps/api/src/browserbase/browserbase.service.ts`	Browser automation (Stagehand + Claude) ~918 lines
`packages/email/`	React Email templates + Resend sending
`packages/device-agent/src/checks/`	Endpoint compliance (macOS, Windows, Linux)
`packages/kv/`	Upstash Redis client
`packages/analytics/`	PostHog tracking

Tier 8: Configuration & DevOps

File	Responsibility
`turbo.json`	Build pipeline, 62 env vars, 15 concurrent tasks
`docker-compose.yml`	Local dev: Postgres, migrations, seeding
`Dockerfile`	Multi-stage production build (6 stages)
`deploy.sh`	ECS deployment verification (10 min timeout)
`buildspec.yml`	AWS CodeBuild validation
`packages/db/prisma/seed/seed.ts`	Database seeding (framework templates)

File Size Hotspots

These files are the largest and most complex, warranting special attention:

File	~Lines	Why It's Big
`questionnaire/utils/content-extractor.ts`	1092	Multi-format parsing (Excel XML, PDF, images, CSV)
`browserbase/browserbase.service.ts`	918	Full browser lifecycle + Stagehand + S3 screenshots
`integration-platform/src/types.ts`	891	Comprehensive manifest types (auth, checks, webhooks)
`cloud-security/cloud-security.service.ts`	702	Multi-provider scan orchestration + credential refresh
`integration-platform/src/runtime/check-context.ts`	538	Rich execution context with 3 pagination strategies
`apps/app/src/utils/auth.ts`	610	Server-side auth wrapper with 15+ methods

Important Prompts (AI System Prompts)

Location	Purpose	Key Rules
`apps/api/src/questionnaire/utils/constants.ts`	RAG answer generation	"ONLY from context", "N/A if insufficient", "we/our voice"
`apps/api/src/cloud-security/ai-remediation.prompt.ts`	AWS fix plans	Zod schema, exact SDK commands, rollback steps
`apps/api/src/cloud-security/gcp-ai-remediation.prompt.ts`	GCP fix plans	REST API endpoints, bearer auth
`apps/api/src/cloud-security/azure-ai-remediation.prompt.ts`	Azure fix plans	ARM REST API, subscription-scoped
`apps/app/src/app/api/policies/[policyId]/chat/route.ts`	Policy editing	"PRESERVE UNCHANGED TEXT", TipTap JSON rules
`apps/api/src/trigger/policies/update-policy-helpers.ts`	Policy generation	Company context injection, framework alignment
`apps/app/src/trigger/tasks/auditor/generate-auditor-content.ts`	Auditor content	"NEVER mention missing info", "no hedging words"
`apps/api/src/assistant-chat/assistant-chat.controller.ts`	General assistant	GRC expert role, current date context
`apps/api/src/soa/utils/soa-answer-generator.ts`	SOA answering	Control-specific, "INSUFFICIENT_DATA" fallback