🔬 ConformEdge — Technical Whitepaper

🔬 ConformEdge — Technical Whitepaper

1. Architecture Overview

ConformEdge is built as a modern, full-stack SaaS application using Next.js 15 with the App Router pattern. The architecture follows a server-first approach — Server Components by default, with client-side interactivity only where required (forms, real-time UI, interactive charts).

All data mutations flow through server actions, providing a unified security boundary where authentication, authorisation, and audit logging are enforced consistently. There is no separate REST API layer for internal operations; the server action pattern eliminates an entire class of API surface area vulnerabilities.

High-Level Architecture

┌─────────────────────────────────────────────────────┐
│                    Client Browser                     │
│  Next.js App Router (React Server Components + CSR)  │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│                  Next.js Server                       │
│  ┌──────────────┐  ┌───────────────┐  ┌───────────┐ │
│  │Server Actions│  │  API Routes   │  │ Middleware │ │
│  │  (mutations) │  │(webhooks/cron)│  │  (Clerk)  │ │
│  └──────┬───────┘  └───────┬───────┘  └───────────┘ │
│         │                  │                          │
│  ┌──────▼──────────────────▼───────┐                 │
│  │        Service Layer            │                 │
│  │  Auth Context │ Audit Logger    │                 │
│  │  AI Engine    │ IMS Engine      │                 │
│  │  Gap Detection│ Notifications   │                 │
│  └──────────────┬──────────────────┘                 │
│                 │                                     │
│  ┌──────────────▼──────────────────┐                 │
│  │     Prisma 7 ORM (adapter-pg)  │                 │
│  └──────────────┬──────────────────┘                 │
└─────────────────┼────────────────────────────────────┘
                  │
    ┌─────────────▼────────────┐
    │     PostgreSQL Database   │
    │    (25+ models, UUIDs)    │
    └──────────────────────────┘

External Services

┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│  Clerk Auth    │  │ Anthropic API  │  │ Google Cloud   │
│  (multi-tenant │  │ (Claude Haiku) │  │  Vision OCR    │
│   orgs + RBAC) │  │                │  │                │
└────────────────┘  └────────────────┘  └────────────────┘

┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│ Cloudflare R2  │  │    Resend      │  │   Paystack     │
│ (file storage) │  │   (email)      │  │  (payments)    │
└────────────────┘  └────────────────┘  └────────────────┘

---

2. Technology Stack

Layer	Technology	Version	Purpose
Framework	Next.js	15	Full-stack React framework (App Router)
Language	TypeScript	5.x	Type safety across the entire codebase
Styling	Tailwind CSS	v4	Utility-first CSS framework
UI Components	shadcn/ui	new-york	Accessible, composable component library
Authentication	Clerk	Latest	Multi-tenant organisations, RBAC, webhooks
Database	PostgreSQL	16	Primary data store
ORM	Prisma	7	Type-safe database access with @prisma/adapter-pg
AI Classification	Anthropic Claude	Haiku	Document-to-clause mapping
OCR	Google Cloud Vision	Latest	Scanned document text extraction
File Storage	Cloudflare R2	-	S3-compatible object storage (zero egress)
PDF Generation	@react-pdf/renderer	Latest	Audit pack and report PDFs
Charts	Recharts	Latest	Dashboard visualisations (9 chart types)
Email	Resend	Latest	Transactional email delivery
Payments	Paystack	Latest	ZAR payment processing
Hosting	Hetzner VPS	-	Production deployment
CI/CD	GitHub Actions	-	Automated deployment pipeline
Process Manager	PM2	Latest	Node.js process management

---

3. AI Classification Engine

How It Works

The AI classification pipeline processes uploaded documents through a multi-stage workflow:

Document Upload → Text Extraction → AI Classification → Gap Update
       │                │                  │                │
       ▼                ▼                  ▼                ▼
  Cloudflare R2    PDF/DOCX parser    Claude Haiku     Coverage %
  (file stored)    or OCR fallback    (clause mapping)  recalculated

Stage 1: Upload & Storage Documents are uploaded via an API route to Cloudflare R2, stored under organisation-scoped keys ({orgId}/{timestamp}-{random}.{ext}). The upload route validates file type, size, and authentication.

Stage 2: Text Extraction

• Native PDFs and DOCX files: Text is extracted programmatically
• Scanned documents and images: Google Cloud Vision OCR extracts text with layout preservation
• The system automatically detects whether OCR is needed based on text extraction quality

Stage 3: AI Classification The extracted text is sent to Anthropic’s Claude Haiku model with a structured prompt that includes:

• The document text (truncated to fit context window)
• The full clause hierarchy for the organisation’s active standards
• Instructions to return clause mappings with confidence scores (0.0-1.0)

The model returns a JSON array of clause matches, each containing:

{
  "clauseId": "uuid",
  "standardId": "uuid",
  "confidence": 0.87,
  "reasoning": "Document contains quality policy commitments matching Clause 5.2"
}

Stage 4: Gap Update Classification results are persisted atomically using db.$transaction() (delete existing + create new). The gap analysis engine immediately recalculates coverage percentages. If coverage for any clause drops below 25%, notifications are triggered.

Confidence Scoring

• High confidence (≥ 0.80): Direct match to clause requirements
• Medium confidence (0.50-0.79): Partial match or supporting evidence
• Low confidence (< 0.50): Tangential relevance, flagged for review

Cross-standard classification applies a 90% confidence decay (capped at 0.85) to ensure primary standard matches rank higher.

Bulk Classification

Bulk classification processes multiple documents with:

• Batching: 3 concurrent API requests to respect Anthropic rate limits
• Progress tracking: Real-time feedback to the user interface
• Error isolation: Individual document failures do not block the batch
• Fire-and-forget pattern with error surfacing via toast notifications

---

4. IMS Intelligence Engine

The Challenge

Organisations maintaining multiple ISO standards face exponential complexity. ISO 9001 (Quality), ISO 14001 (Environmental), and ISO 45001 (OH&S) share significant overlapping requirements — leadership commitment, risk management, document control, internal audit, management review — but the specific clause numbering differs across standards.

Manually tracking these overlaps across 7 standards with ~441 cross-references is impractical.

Union-Find Equivalence Grouping

ConformEdge implements a Union-Find (disjoint-set) data structure to group equivalent clauses across standards into equivalence classes:

Standard A, Clause 4.1 ←→ Standard B, Clause 4.1 ←→ Standard C, Clause 4.1
         └──────────── Equivalence Group ────────────┘

Algorithm:

1. Load all cross-reference mappings from the database (~441 records)
2. Build a Union-Find forest where each clause is a node
3. For each cross-reference, union the two clauses
4. Find operations with path compression identify equivalence groups
5. Each group represents a set of clauses that share requirements

Benefits:

• Transitive closure: If A↔B and B↔C, the engine automatically knows A↔C
• O(α(n)) amortised time per operation (effectively constant)
• Deterministic grouping regardless of insertion order

Integration Scoring

The IMS engine calculates an integration score (0-100%) based on:

• Document coverage overlap: How many equivalence groups have documents classified across multiple standards
• Gap symmetry: Whether gaps exist consistently or inconsistently across equivalent clauses
• CAPA cross-linking: Whether corrective actions reference multiple standards

A high integration score indicates a well-functioning IMS where standards reinforce each other.

Gap Cascades

When a document is classified or a gap is closed for one clause, the engine:

1. Identifies the equivalence group for that clause
2. Recalculates coverage for all equivalent clauses across standards
3. Generates cross-standard suggestions (e.g., “This document also satisfies ISO 14001 Clause 7.5”)
4. Updates gap analysis dashboards in real time

This cascade effect means a single document upload can improve compliance scores across multiple standards simultaneously.

Shared Requirements Matrix

The engine generates a consolidated matrix showing:

• All equivalence groups with their member clauses
• Current coverage status per group
• Documents satisfying each group
• Outstanding gaps requiring attention

This matrix is invaluable for auditors conducting integrated management system audits.

---

5. Security Model

Authentication & Authorisation

Clerk Integration:

• All authentication flows (sign-up, sign-in, MFA, SSO) are handled by Clerk
• Webhook endpoint (/api/webhooks/clerk) synchronises users and organisations to the local database
• Middleware (src/middleware.ts) protects all dashboard routes

RBAC Enforcement: Five roles with hierarchical permissions:

Role	View	Create	Edit	Delete	Admin
OWNER	✅	✅	✅	✅	✅
ADMIN	✅	✅	✅	✅	✅
MANAGER	✅	✅	✅	❌	❌
AUDITOR	✅	✅*	❌	❌	❌
VIEWER	✅	❌	❌	❌	❌

*Auditors can create assessments and findings only.

RBAC is enforced at the server action level via getAuthContext(), which is wrapped in React cache() for per-request deduplication. Every mutation checks canEdit, canCreate, or canDelete before proceeding.

Data Isolation

Multi-tenant data isolation is enforced at the database query level:

• Every query includes an organizationId filter
• The organisation ID is derived from the authenticated Clerk session (not from user input)
• R2 storage keys are prefixed with the organisation ID
• Download routes verify the first key segment matches the authenticated organisation

Audit Trail

All mutations are logged via logAuditEvent() in src/lib/audit.ts:

• Actor (user ID, name, role)
• Action (CREATE, UPDATE, DELETE, APPROVE, REJECT, etc.)
• Entity type and ID
• Timestamp
• IP address (where available)
• Organisation context

The audit trail is immutable and queryable via the Audit Trail dashboard page.

Token Security

External access (client portal, subcontractor portal) uses token-based authentication:

• Tokens are generated using cryptographically secure random bytes
• The raw token is shown to the creator exactly once
• Only the SHA-256 hash is stored in the database
• Validation compares the hash of the presented token against the stored hash
• Tokens have configurable expiry dates
• Access is logged with view counts and timestamps

File Access Security

• Path traversal guards validate that resolved file paths stay within allowed directories
• R2 download route uses presigned URLs with authentication gating
• Organisation-scoped storage keys prevent cross-tenant file access
• Legacy file paths (/public/uploads/) are supported with the same security guards

---

6. Multi-Tenant Architecture

Clerk Organisations

ConformEdge leverages Clerk’s organisation feature for multi-tenancy:

Clerk Organisation ←→ ConformEdge Organisation (1:1)
     │                         │
     ├── Members               ├── Documents
     ├── Roles                 ├── Assessments
     └── Invitations           ├── CAPAs
                               ├── Checklists
                               └── Settings

• Each Clerk organisation maps to exactly one ConformEdge organisation
• Users can belong to multiple organisations (critical for consultants)
• Switching organisations in Clerk automatically scopes all ConformEdge queries
• Organisation settings (including feature flags like auto-classify) are stored in a JSON column

Consultant Model

ISO consulting firms operate as follows:

1. The consultant creates a Clerk organisation for each client
2. The consultant user is added as OWNER or ADMIN to each client organisation
3. Client users are invited to their own organisation with appropriate roles
4. The consultant switches between organisations to manage each client
5. Cross-client reporting is available at the consultant level

This architecture provides:

• Full data isolation between clients
• Independent billing per client organisation
• Role separation — the consultant sees everything, client staff see their own data
• Scalability — no limit on the number of client organisations

---

7. Database Schema

Overview

The database comprises 25+ Prisma models with the following characteristics:

• UUID primary keys throughout (no sequential IDs)
• Snake_case naming via @map/@@map decorators
• Soft references where appropriate (SetNull on delete for lineage tracking)
• JSON columns for flexible configuration (settings, field configs, responses)

Core Models

Model	Purpose	Key Relationships
Organization	Tenant root	Has many of all entities
User	Authenticated users	Belongs to organizations via membership
ISOStandard	7 seeded standards	Has many clauses
StandardClause	49 top-level + 187 sub-clauses	Belongs to standard, has cross-references
Document	Compliance documents	Has classifications, versions
DocumentClassification	AI clause mappings	Links document to clause with confidence
Assessment	Internal audits	Has findings, linked to standard
AssessmentFinding	Audit findings	Linked to clause, may generate CAPA
CorrectiveAction	CAPAs	Cross-standard via junction table
CapaStandardClause	Cross-standard CAPA links	Junction: CAPA ↔ Clause
ChecklistTemplate	Reusable templates	Has items with field types
ComplianceChecklist	Active checklists	From template, has items
ChecklistItem	Individual items	Field type, config, response (JSON)
AuditPack	Generated packs	Compiled from multiple entities
Subcontractor	External companies	Has certifications
SubcontractorCertification	Certificates	Status: PENDING_REVIEW/APPROVED/REJECTED
ApprovalWorkflowTemplate	Approval chains	Has steps (sequential)
ApprovalRequest	Active approvals	For a document, has steps
ApprovalStep	Individual approvals	Reviewer, decision, comments
ShareLink	External access tokens	Hashed token, expiry, access log
ShareLinkAccess	Access audit log	Token, timestamp, IP
Notification	In-app + email alerts	13 types, read/unread status
AuditEvent	Immutable audit trail	Actor, action, entity, timestamp

ISO Standards Data

7 standards are seeded with comprehensive clause hierarchies:

Standard	Top-Level Clauses	Sub-Clauses	Cross-References
ISO 9001:2015	10	~40	~80
ISO 14001:2015	10	~30	~70
ISO 45001:2018	10	~30	~70
ISO 27001:2022	10	~25	~60
ISO 22301:2019	10	~20	~50
ISO 37001:2016	10	~20	~55
ISO 39001:2012	10	~22	~56
Total	49	~187	~441

Seed data is maintained in prisma/seed-data/ with individual files per standard.

Indexing Strategy

Performance-critical queries are supported by targeted indexes:

• @@index([isRecurring, isPaused, nextDueDate]) on ChecklistTemplate for cron queries
• Organisation ID indexes on all tenant-scoped tables
• Composite indexes on frequently filtered columns (status, type, date ranges)

---

8. API & Integration

Cron Workflows

A scheduled cron endpoint (/api/cron/check-expiries) handles time-based automation — this is the technical foundation of ConformEdge’s penalty prevention capability. Every deadline, every expiry, every upcoming assessment is monitored automatically so that nothing slips through the cracks:

Task	Trigger	Action
Document expiry	30/7/1 days before expiry	Send notification to document owner
Assessment overdue	Past scheduled date	Send notification to assessor + managers
Assessment upcoming	7/1 days before	Send reminder to assessor
Share link expiry	Past expiry date	Mark ACTIVE → EXPIRED
Recurring checklists	nextDueDate ≤ now	Generate checklist, advance nextDueDate, notify assignee
CAPA escalation	7 days overdue	Bump priority, notify managers
Checklist due dates	7/1 days before	Send reminder to assignee

Webhook Sync

Clerk webhooks (/api/webhooks/clerk) synchronise:

• User creation, update, and deletion
• Organisation creation, update, and deletion
• Organisation membership changes (role assignment)

The webhook handler validates the Svix signature before processing.

R2 Storage Integration

File operations use Cloudflare R2 via S3-compatible SDK:

• Upload: POST /api/upload → Multipart upload to R2
• Download: GET /api/download/[...key] → Presigned URL redirect
• Key format: {orgId}/{timestamp}-{random}.{ext}
• Discrimination: isR2Key() utility distinguishes R2 keys from legacy /uploads/ paths

Email Delivery

Resend handles all transactional email:

• Approval request notifications
• Assessment reminders
• CAPA escalation alerts
• Audit pack delivery
• Share link invitations
• Subcontractor portal invitations

---

9. Performance & Scalability

Current Architecture

The application runs on a single Hetzner VPS managed by PM2:

• Max memory restart: 768 MB per process
• Exponential backoff: 1,000 ms base delay on crash recovery
• Health check: GitHub Actions deployment verifies endpoint availability

Database Performance

• Prisma 7 with @prisma/adapter-pg for connection pooling (max 5 connections)
• Global singleton pattern prevents connection exhaustion in development
• UUID primary keys provide even index distribution
• Targeted indexes on high-query columns

AI Classification Performance

• Individual classification: 2-5 seconds per document
• Bulk classification: 3 concurrent requests, ~20 documents per minute
• OCR fallback: 3-8 seconds additional for scanned documents
• Classification results cached in database (re-classify on demand)

Scalability Path

The architecture supports horizontal scaling through:

1. Database: Migration to managed PostgreSQL (e.g., Supabase, Neon) for connection pooling and read replicas
2. Application: PM2 cluster mode or containerised deployment (Dockerfile included)
3. Storage: Cloudflare R2 scales automatically with zero configuration
4. AI: Anthropic API scales with API key limits (upgradeable)
5. CDN: Next.js static assets can be served via Cloudflare CDN

---

10. Compliance & Data Residency

Hosting

• Primary server: Hetzner VPS (European data centre, SA-accessible)
• File storage: Cloudflare R2 (global edge network)
• Authentication: Clerk (US-hosted, SOC 2 Type II certified)
• AI processing: Anthropic API (US-hosted, SOC 2 certified)

Data Handling

• All document content is processed transiently for AI classification — no document content is stored by Anthropic
• File storage in Cloudflare R2 with organisation-scoped access controls
• Database backups configured per hosting provider standards
• Audit trail provides full accountability for all data access and mutations

POPIA Considerations

For South African customers, ConformEdge supports POPIA (Protection of Personal Information Act) compliance through:

• Purpose limitation: Data is collected and processed solely for compliance management
• Data minimisation: Only necessary information is stored
• Security safeguards: Encryption in transit (TLS), access controls, audit logging
• Right to access: Audit trail provides complete data access history
• Data export: Reports and data can be exported in CSV and PDF formats

Future Data Residency

The architecture supports future deployment to SA-based cloud providers should data residency requirements mandate it. The containerised deployment model (Docker) enables infrastructure portability.

---

Appendix: Key File References

Component	Path
AI Classification	src/lib/ai/classify-document.ts
OCR Extraction	src/lib/ai/ocr-extract.ts
IMS Engine	src/lib/ims/ims-engine.ts
Cross-Standard Suggestions	src/lib/ims/cross-standard-suggestions.ts
Gap Detection	src/lib/gap-detection.ts
Auth Context	src/lib/auth.ts (cached)
Audit Logger	src/lib/audit.ts
R2 Storage	src/lib/r2.ts, src/lib/r2-utils.ts
Share Token Utils	src/lib/share-tokens.ts
Recurrence Calculator	src/lib/recurrence.ts
Assessment Status	src/lib/assessment-status.ts
Database Singleton	src/lib/db.ts
Prisma Schema	prisma/schema.prisma
Clerk Middleware	src/middleware.ts

---

ConformEdge Technical Whitepaper v1.0 — ISU Technologies (Pty) Ltd