Compliance Module Specification

Purpose

The compliance module implements the Compliance Domain inside the Spring Boot Modulith. It manages procurement readiness, requirements, documents, evidence, verification, expiry monitoring, tender-specific compliance interpretation, compliance risk, and South African procurement context including SARS, CIPC, CSD, CIDB, COIDA, B-BBEE, and tax compliance evidence.

Owned Domain

Compliance owns compliance requirements, compliance documents, evidence, verification records, expiry state, tender-specific compliance requirements, Procurement Readiness Score, compliance gaps, compliance risks, and compliance AI suggestion review outcomes. It references Organization facts but does not own legal organization profile data.

Owned Aggregates

Aggregate	Responsibility
Compliance Profile	Root aggregate for an organization's compliance status, readiness, and risk summary.
Compliance Requirement Set	General and tender-specific requirement definitions, applicability, and satisfaction criteria.
Compliance Evidence Register	Documents, evidence items, expiry, and evidence status.
Verification Case	Verification workflow, method, result, reviewer, and audit.
Readiness Assessment	Procurement Readiness Score, components, gaps, and calculation result.
Compliance Risk Assessment	Risk state, severity, cause, and remediation path.

Owned Entities

Compliance Profile, Compliance Requirement, Tender Compliance Requirement, Compliance Document, Compliance Evidence, Verification Record, Expiry Alert, Readiness Assessment, Compliance Risk, Compliance Gap, and Compliance Suggestion.

Owned Value Objects

ComplianceProfileId, ComplianceRequirementId, ComplianceDocumentType, ComplianceStatus, VerificationStatus, ExpiryDate, RenewalWindow, ProcurementReadinessScore, ComplianceRiskLevel, EvidenceStrength, ComplianceSource, RequirementApplicability, and AISuggestionConfidence.

Commands

Command	Responsibility
CreateComplianceProfile	Create organization-bound compliance profile after organization registration.
AddComplianceRequirement	Add or update a compliance requirement definition.
CaptureTenderComplianceRequirements	Record tender-specific requirements from opportunity context.
UploadComplianceDocument	Register a compliance document and metadata.
LinkComplianceEvidence	Link evidence to a requirement.
VerifyComplianceEvidence	Record verification result and reviewer context.
EvaluateDocumentExpiry	Update expiry state and alert/risk outputs.
RecalculateProcurementReadiness	Recalculate readiness score and gaps.
IdentifyComplianceRisk	Create or update risk based on missing, expired, weak, or conflicting evidence.
ResolveComplianceRisk	Mark risk resolved with resolution evidence.
ReviewComplianceAISuggestion	Accept, reject, or hold AI suggestion for human review.

Queries

Query	Responsibility
GetComplianceProfile	Return organization-bound compliance summary.
GetComplianceRequirements	Return applicable requirements and source context.
GetTenderComplianceRequirements	Return requirements interpreted for an opportunity.
GetComplianceDocuments	Return document metadata, status, and expiry.
GetEvidenceCoverage	Return evidence-to-requirement coverage view.
GetVerificationRecords	Return verification history where authorized.
GetExpiryDashboard	Return expiring, expired, and renewal-required items.
GetProcurementReadiness	Return score, components, gaps, and explanation.
GetComplianceRisks	Return risks, severity, cause, and remediation status.
GetSouthAfricanComplianceSummary	Return SARS, CIPC, CSD, CIDB, COIDA, B-BBEE, and tax compliance summary where applicable.

Application Services

ComplianceProfileApplicationService, RequirementApplicationService, TenderRequirementApplicationService, ComplianceDocumentApplicationService, EvidenceApplicationService, VerificationApplicationService, ExpiryMonitoringApplicationService, ReadinessApplicationService, ComplianceRiskApplicationService, and ComplianceAISuggestionApplicationService.

Domain Services

ComplianceProfileCreationService, DocumentExpiryService, EvidenceVerificationService, ProcurementReadinessScoringService, ComplianceRiskService, TenderRequirementService, and AISuggestionReviewService.

Policies

Compliance Profile Creation Policy, Document Expiry Policy, Evidence Verification Policy, Procurement Readiness Scoring Policy, Compliance Risk Policy, Tender Requirement Policy, AI Suggestion Review Policy, and Cross-Domain Ownership Policy.

Repositories

ComplianceProfileRepository, ComplianceRequirementRepository, TenderComplianceRequirementRepository, ComplianceDocumentRepository, ComplianceEvidenceRepository, ComplianceVerificationRepository, ExpiryAlertRepository, ReadinessAssessmentRepository, ComplianceRiskRepository, ComplianceGapRepository, ComplianceAISuggestionRepository, and ComplianceAuditRepository.

Events Published

ComplianceProfileCreated, ComplianceRequirementAdded, TenderComplianceRequirementsCaptured, ComplianceDocumentUploaded, ComplianceDocumentExpired, ComplianceEvidenceLinked, ComplianceEvidenceVerified, ProcurementReadinessScoreUpdated, ComplianceRiskIdentified, ComplianceRiskResolved, AISuggestionReceived, AISuggestionAccepted, and AISuggestionRejected.

Events Consumed

OrganizationRegistered, OrganizationProfileUpdated, CapabilityVerified, DirectorAdded, CertificationAdded, LicenceAdded, TenderRequirementCaptured, BidNoBidRecommendationCreated, TenderWorkspaceCreated, SBDFormPrepared, SubscriptionSuspended, and AdministrativePolicyChanged. Consumed events trigger compliance-owned commands, read model updates, or review tasks only.

REST API Responsibility

The module owns API responsibilities for compliance profiles, requirements, tender-specific requirements, compliance documents, evidence, verification, expiry, readiness, risks, gaps, AI suggestion review, and country-specific compliance summaries. Final endpoint paths and OpenAPI schemas are deferred.

Database Ownership

Compliance owns conceptual persistence for compliance profiles, compliance requirements, tender compliance requirements, compliance documents, compliance evidence, verifications, expiry alerts, procurement readiness assessments, compliance risks, compliance gaps, compliance AI suggestions, and compliance audit logs.

Module Dependencies

Allowed dependencies are shared kernel identifiers, identity authorization checks, organization profile and capability references, opportunity tender requirement events and read models, bid submission readiness events, notification expiry and risk triggers, analytics event projections, intelligence AI suggestions, and integration gateway references for external compliance evidence.

Forbidden Dependencies

Compliance must not mutate Organization identity, tender source records, bid workspaces, contract obligations, notification delivery records, analytics projections, or raw AI memory records. Other modules must not update compliance evidence, verification, readiness, expiry, or risk tables directly.

AIOS Interaction Boundary

AIOS may suggest requirements, document classifications, evidence mappings, readiness explanations, remediation actions, and risk summaries through Compliance application services. Compliance must review and accept suggestions before changing compliance facts.

Security And Tenant Rules

• Every compliance record is organization-bound and must include tenant context.
• Compliance documents and evidence require document access control and audit logging.
• Verification actions require role, permission, and actor context.
• Expired documents must not satisfy active requirements without explicit exception policy.
• External compliance evidence from SARS, CIPC, CSD, CIDB, COIDA, or B-BBEE sources must retain provenance and retrieval context.

Test Strategy

Tests must cover requirement applicability, document expiry, evidence linking, verification state transitions, readiness scoring, risk identification and resolution, AI suggestion review, event publication, idempotent event consumption, document access controls, tenant filtering, repository ownership, and Spring Modulith boundary verification.

Future Microservice Extraction Notes

Compliance can be extracted when requirements, verification, document evidence, and readiness APIs are stable. Extraction requires event contracts for Organization and Opportunity dependencies, document storage contracts, tenant-aware data migration, and no direct table usage by Bid or Opportunity.

Mermaid Component Diagram

flowchart TD
    Api[compliance.api.rest]
    App[compliance.application.service]
    Command[compliance.application.command]
    Query[compliance.application.query]
    Domain[compliance.domain.model]
    Policy[compliance.domain.policy]
    Repo[compliance.infrastructure.persistence]
    Integration[compliance.infrastructure.integration]
    Messaging[compliance.infrastructure.messaging]
    Organization[organization context]
    Opportunity[opportunity tender requirements]
    Bid[bid readiness requests]
    Intelligence[intelligence suggestions]
    Notification[notification triggers]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Integration
    App --> Messaging
    App --> Organization
    App --> Opportunity
    App --> Bid
    App --> Intelligence
    Messaging --> Notification