02 - Core Logic & Data Flow

Compliance Domain Model

The core data model follows a hierarchical compliance structure:

Organization
  ├── Frameworks (SOC 2, ISO 27001, HIPAA, GDPR)
  │     └── Controls
  │           └── Requirements
  ├── Tasks
  │     ├── Task Items (checklist sub-tasks)
  │     ├── Comments
  │     └── Attachments (evidence files)
  ├── Policies (generated/edited TipTap JSON documents)
  ├── Risks (risk register with mitigation)
  ├── Vendors (third-party risk assessment)
  ├── Findings (security findings from scans)
  ├── People (employees/contractors)
  ├── Devices (endpoint inventory)
  ├── Context (organization Q&A for LLM context)
  ├── Integrations (connected cloud services)
  ├── Questionnaires (security questionnaire responses)
  ├── Knowledge Base Documents (uploaded reference docs)
  └── Training (security awareness modules)

Key relationships:

• An Organization subscribes to one or more Frameworks
• Each Framework defines Controls, which map to Requirements
• Tasks represent actionable compliance work items assigned to members
• Policies are TipTap JSON documents generated by LLMs and reviewed by humans
• Evidence (attachments) can be linked to tasks as proof of compliance
• The Statement of Applicability (SOA) maps controls to their implementation status

Key NestJS Modules

Each module follows the NestJS convention of controller + service + optional guards/DTOs:

Auth (apps/api/src/auth/)

• HybridAuthGuard — dual API key / JWT authentication
• ApiKeyService — API key hashing (SHA256), validation, expiration checks
• Decorators: @AuthContext(), @OrganizationId(), @UserId(), @IsApiKeyAuth()

Organization (apps/api/src/organization/)

• Multi-tenant org management
• Member CRUD with role-based access
• Onboarding state tracking

Tasks (apps/api/src/tasks/)

• Task CRUD with assignee management
• Evidence export (PDF/ZIP) via EvidenceExportModule
• Task item (sub-task) checklist management

Policies (apps/api/src/policies/)

• Policy CRUD and publishing workflow
• TipTap JSON document storage
• Policy acceptance tracking (via portal)

Risks (apps/api/src/risks/)

• Risk register with likelihood/impact scoring
• AI-generated risk mitigation recommendations

Vendors (apps/api/src/vendors/)

• Vendor inventory and risk categorization
• AI-powered vendor risk assessment using structured output
• Web research via Firecrawl for vendor due diligence

Findings (apps/api/src/findings/)

• Security findings from cloud scans and manual entry
• Finding templates for common vulnerability types

Cloud Security (apps/api/src/cloud-security/)

• AWS SecurityHub integration for automated scanning
• Cloud test definitions and result tracking
• Transactional scan run and results creation

Questionnaire (apps/api/src/questionnaire/)

• Security questionnaire file upload and parsing
• RAG-based automatic answer generation
• Batch processing with streaming progress updates

Vector Store (apps/api/src/vector-store/)

• Upstash Vector embedding management
• Sync pipelines: policies, context Q&A, knowledge base docs, manual answers
• Semantic search for RAG retrieval

Integration Platform (apps/api/src/integration-platform/)

• Runtime for executing integration test suites
• Connects to @comp/integration-platform package registry

Training (apps/api/src/training/)

• Security awareness training module management
• Video-based training content

Data Flow Diagrams

Task Completion Flow

User marks task complete (frontend)
  → Server action / API call
  → TasksService.update(taskId, { status: 'done' })
  → Prisma → PostgreSQL
  → Revalidate task list cache
  → If all tasks for a control are done:
      → Control status updates
      → Framework completion % recalculated

Evidence Collection Flow

User uploads file (frontend)
  → Presigned S3 URL generation
  → File uploaded to AWS S3
  → AttachmentsService.create(taskId, s3Key, metadata)
  → Prisma → PostgreSQL
  → Evidence linked to task
  → Available for export (PDF/ZIP) via EvidenceExportModule

Policy Generation Flow

Organization onboarding triggers policy generation
  → Trigger.dev: generate-full-policies task
  → For each policy template:
      → Load template (TipTap JSON with Handlebars conditionals)
      → Build context from organization Q&A (Context Hub)
      → generatePrompt() builds LLM prompt with:
          - Company name, website
          - Framework conditionals (SOC2, HIPAA flags)
          - Placeholder mapping ({{COMPANY}}, {{INDUSTRY}}, etc.)
          - Knowledge base context
      → LLM generates final TipTap JSON
      → Save to DB as draft policy
  → Email notifications to stakeholders

Vendor Risk Assessment Flow

User adds vendor with website URL
  → Trigger.dev: research task (Firecrawl)
      → Scrape vendor website
      → Poll for completion (5s intervals, 5min timeout)
      → Validate response with Zod schema
  → Trigger.dev: generate-vendor-mitigation task
      → LLM structured output (Zod schema)
      → Risk scoring and categorization
      → pg_advisory_lock for concurrent write safety
      → Save assessment to DB

Database

PostgreSQL + Prisma ORM

Schema location: packages/db/prisma/schema/ (30 modular .prisma files)

Schema composition: The packages/db/scripts/combine-schemas.js script concatenates all 30 .prisma files (plus the base schema.prisma) into a single dist/schema.prisma for distribution and client generation.

Background Jobs (Trigger.dev)

Jobs are defined as Trigger.dev v4 tasks with retry policies and scheduling:

Onboarding Pipeline

onboard-organization
  ├── Seed framework controls and requirements
  ├── Create initial tasks from templates
  ├── generate-full-policies (batch LLM generation)
  ├── generate-risk-mitigation (AI risk assessment)
  ├── generate-vendor-mitigation (AI vendor assessment)
  ├── backfill-executive-context (org context generation)
  └── backfill-training-videos (training content setup)

Scheduled Jobs

• task-schedule: Creates recurring compliance tasks based on control schedules
• policy-schedule: Triggers periodic policy review cycles
• weekly-task-reminder: Sends email digest of pending tasks per member
• integration-schedule: Runs periodic integration test suites

Integration Sync

integration-schedule (cron)
  → run-integration-tests (per integration)
  → integration-results (process and store)

Integration Platform

Package: packages/integration-platform/

The integration platform uses a registry pattern with manifest-based plugin validation:

IntegrationRegistryImpl (singleton)
  ├── validateManifest() — checks id, name, auth strategy, capabilities
  ├── getManifest(id)
  ├── getAllManifests()
  ├── getByCategory(category)
  ├── getActiveManifests()
  ├── requiresOAuth(id)
  └── getHandler(id)

Registered integrations (10):

Each manifest declares:

• id, name, description, category
• auth strategy (oauth2 config or API key)
• capabilities (list of test types the integration supports)
• handler (runtime execution logic)
• isActive flag