Reference Architecture
High-level architecture overview, system boundaries, and logic flow for enterprise evaluation and procurement review.
This section is intended for: Technical Team, Auditor, Management. Unauthorised access is restricted.
1. Purpose
This document provides architectural transparency for CISOs, auditors, and procurement officers evaluating the platform. It describes the system's structural design, data flow, and governance enforcement points.
This architecture description reflects the current implemented system. It is not aspirational or roadmap-based.
2. High-Level Architecture
The following diagram illustrates the layered architecture of the Govula platform, from client-facing components through governance services to the persistent data layer.
┌─────────────────────────────────────────────────────────────┐ │ CLIENT LAYER │ │ Next.js 15 (React 19) • TailwindCSS • Role-Based Views │ ├─────────────────────────────────────────────────────────────┤ │ API GATEWAY │ │ Express.js 5 • JWT Auth • RBAC Middleware • Rate Limiting │ ├──────────┬──────────┬──────────┬──────────┬─────────────────┤ │ GOVERNANCE│ WORKSPACE │ EVIDENCE │ REPORTING │ IDENTITY │ │ ENGINE │ SERVICE │ SERVICE │ SERVICE │ SERVICE │ │ │ │ │ │ │ │ Decision │ Audience │ Quality │ Governed │ SSO/MFA │ │ Registry │ Binding │ Index │ Reports │ RBAC │ │ Constitu-│ Pre- │ Version │ Lineage │ Session │ │ tion │ flight │ Control │ Appendix │ Management │ │ Truth │ Guards │ Freshness│ Signing │ │ │ Envelope │ │ │ │ │ ├──────────┴──────────┴──────────┴──────────┴─────────────────┤ │ INSTITUTIONAL MEMORY │ │ Immutable Audit Stream • Hash Chain • Governance Timeline │ ├─────────────────────────────────────────────────────────────┤ │ DATA LAYER │ │ PostgreSQL • Tenant Isolation • Append-Only Patterns │ └─────────────────────────────────────────────────────────────┘
3. Governance Enforcement Points
Governance is enforced at multiple points in the request lifecycle. Each enforcement point acts as a gate that must be satisfied before processing continues.
Authentication Gate
Every request passes through JWT verification.
Role Authorization
Role-based middleware checks before route handlers.
Workspace Resolution
Audience binding resolves the authoritative workspace.
Governance Enforcement Point — Pre-Flight Validation
Governance Guardrails (Pre-flight Validation)
Govula enforces governance correctness through deterministic pre-flight validation. Before a workspace can be activated or an authoritative report generated, the platform verifies that minimum governance conditions are satisfied — including framework applicability, control mapping, and ownership assignment.
These checks exist to prevent the creation or publication of incomplete, misleading, or non-defensible compliance artefacts. They do not introduce interpretation, scoring, or automated judgement.
If a pre-flight validation fails, no existing artefacts are altered. The system provides explicit remediation guidance, and governance authority remains unchanged until requirements are met.
Scope Validation
Report scope validated against governance context.
Decision Authority Check
Constitution service verifies role authority for decision class.
Immutability Enforcement
Locks prevent modification of finalised artefacts.
Audit Capture
Every governance action appended to immutable audit stream.
4. Data Flow Narrative
The following narratives describe the data flow for key platform operations, illustrating how governance is enforced at each stage.
Compliance Decision Flow
User submits decision → Role authority verified → Decision class validated → Separation of duties checked → Decision registered with hash chain → Audit entry appended → Notification triggered
Report Generation Flow
User requests report → Audience binding resolved → Workspace governance context loaded → Pre-flight guardrails validated → Decision versions locked → Report content generated → SHA-256 hash computed → Cryptographic signature applied → Governed report stored → Lineage appendix attached (auditor reports)
Evidence Ingestion Flow
Evidence submitted → Quality index calculated → Freshness timestamp recorded → Version chain updated → Control mapping verified → Audit entry appended
5. System Boundary Declarations
The following table summarises the platform's operational boundaries, declaring what the system does and does not do.
| Capability | Status | Boundary |
|---|---|---|
| Compliance decision management | Active | Advisory and binding decisions with role-based authority |
| Evidence lifecycle tracking | Active | Ingestion, versioning, freshness monitoring |
| Governed report generation | Active | Locked to decision versions with cryptographic signing |
| AI-powered analysis | Active | Recommendations only; cannot approve, sign, or publish |
| Continuous monitoring | Not implemented | Platform does not perform real-time infrastructure scanning |
| Auto-remediation | Not implemented | Platform does not automatically fix compliance gaps |
| SIEM integration | Not implemented | Platform is not a security event management system |
| Certification issuance | Not implemented | Platform does not issue compliance certificates |
6. Technology Stack Summary
| Component | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 15, React 19 | Role-based dashboard and documentation |
| API | Express.js 5, TypeScript | Business logic and governance enforcement |
| Database | PostgreSQL | Persistent storage with tenant isolation |
| Authentication | JWT, SAML 2.0, OIDC | Identity and session management |
| AI | OpenAI GPT-4o-mini | Advisory analysis and recommendations |
| Signing | SHA-256, HMAC | Content integrity and tamper detection |