# Governex Compliance Solutions — Platform Architecture & Features

## Overview
Governex is a **Governance, Risk & Compliance (GRC)** platform designed for companies in **Lesotho and Southern Africa**. It is a unified system that helps organisations manage risk, compliance, audits, occupational health & safety, fraud reporting, and document management from a single interface.

**Target industries**: Telecom, Banking & Finance, Construction, Education (Schools), Insurance, Manufacturing, Government Institutions.

**Design principles**: Simple, secure, scalable, mobile-friendly.

---

## Tech Stack
- **Backend**: Laravel 10 (PHP)
- **Frontend**: Vue 3 + Inertia.js (SPA feel with server-side routing)
- **UI Components**: PrimeVue 4 (Aura theme), Lucide Vue Icons
- **Styling**: Tailwind CSS 3 with custom brand tokens (see `ui-design-system.md`)
- **Auth**: Laravel Jetstream (Inertia stack) with Sanctum
- **Build**: Vite 5
- **Database**: MySQL

---

## Core Modules

### 1. Risk Management
**Purpose**: Enable organisations to identify, assess, prioritise, and mitigate risks across all business units.

| Feature | Description |
|---|---|
| Dynamic Risk Register | Central register of all organisational risks, categorised by type, department, and status |
| Risk Scoring Matrix | Automated scoring using **likelihood × impact** formula (e.g. 5×5 matrix) with configurable scales |
| Risk Dashboards | Visual dashboards with risk heat maps, trending charts, and summary KPIs for management and board reporting |
| Risk Owner Assignment | Assign each risk to a responsible person; track accountability |
| Mitigation Tracking | Log mitigation plans, set deadlines, track progress, and record residual risk after treatment |
| Risk Appetite & Tolerance | Define organisational risk appetite and flag risks exceeding tolerance thresholds |

**Key entities**: `Risk`, `RiskCategory`, `RiskOwner`, `MitigationPlan`, `RiskAssessment`

---

### 2. Compliance Management
**Purpose**: Track regulatory obligations, ensure ongoing compliance, and maintain evidence for auditors and regulators.

| Feature | Description |
|---|---|
| Compliance Register | Central repository of all applicable regulations, standards, and internal policies |
| Obligation Tracking | Map obligations to specific controls, departments, and responsible persons |
| Automated Reminders & Alerts | Scheduled notifications for upcoming deadlines, expiring certifications, and overdue reviews |
| Evidence Upload | Upload and link supporting evidence (documents, screenshots, certificates) to compliance items |
| Compliance Status Dashboard | Visual overview of compliance posture — compliant, partially compliant, non-compliant |
| Regulatory Mapping | Map regulations to specific industry requirements (e.g. banking regulations, telecom standards) |

**Key entities**: `ComplianceObligation`, `ComplianceEvidence`, `ComplianceReview`, `Regulation`, `Standard`

---

### 3. Safety File & Environmental Documentation
**Purpose**: Generate and manage safety files, Environmental Impact Assessments (EIA), Environmental and Social Management Plans (ESMP), and other regulatory documentation.

| Feature | Description |
|---|---|
| Safety File Generation | Structured templates for generating safety files per project or site |
| ESMP Generation | Environmental and Social Management Plan document builder |
| EIA Documentation | Environmental Impact Assessment tracking and document management |
| Template Library | Pre-built templates for common regulatory documents |
| Version History | Track all revisions and approvals of generated documents |

**Key entities**: `SafetyFile`, `DocumentTemplate`, `GeneratedDocument`, `DocumentVersion`

---

### 4. Audit Management
**Purpose**: Plan, schedule, execute, and report on internal audits with structured workflows.

| Feature | Description |
|---|---|
| Audit Planning & Scheduling | Create annual audit plans, schedule individual audits, assign audit teams |
| Audit Checklists | Configurable checklists tied to standards, regulations, or internal procedures |
| Working Papers | Digital working paper management — attach findings, evidence, and notes per checklist item |
| Lead Auditor Workflow | Structured review and approval flow: auditor → reviewer → lead auditor → sign-off |
| Audit Findings | Log findings with severity levels, link to corrective actions (CAPA) |
| Full Audit Trail | Every action is timestamped and attributed — who did what, when |
| Audit Reports | Auto-generated audit reports with findings, recommendations, and management responses |

**Key entities**: `AuditPlan`, `Audit`, `AuditChecklist`, `AuditFinding`, `AuditWorkingPaper`, `AuditTeam`

---

### 5. Corrective Action Tracking (CAPA)
**Purpose**: Log non-conformances from audits, inspections, or incidents, assign corrective/preventive actions, and track resolution.

| Feature | Description |
|---|---|
| Non-Conformance Logging | Record non-conformances with description, source (audit, incident, inspection), severity |
| Corrective Action Assignment | Assign actions to responsible persons with due dates |
| Root Cause Analysis | Document root cause investigation (e.g. 5 Whys, Fishbone) |
| Automated Reminders | Email/notification reminders for upcoming and overdue actions |
| Escalation Rules | Auto-escalate overdue actions to managers after configurable thresholds |
| Verification & Close-Out | Verify effectiveness of corrective action before closing |
| CAPA Dashboard | Track open, overdue, and closed actions with trend analysis |

**Key entities**: `NonConformance`, `CorrectiveAction`, `RootCauseAnalysis`, `CAPAVerification`

---

### 6. Occupational Health & Safety (OHS) Module
**Purpose**: Manage workplace safety — incident reporting, inspections, employee health, and hazard identification.

| Feature | Description |
|---|---|
| Incident & Accident Reporting | Structured forms for reporting workplace incidents and accidents |
| Near-Miss Reporting | Capture near-miss events to enable proactive safety management |
| Employee Health Records | Track medical fitness, fitness-for-work certificates, and health monitoring schedules |
| Safety Inspections | Schedule and conduct inspections using configurable checklists |
| Hazard Identification | Log identified hazards, assess risk, and link to controls and mitigation |
| Safety Statistics | Track LTIFR, TRIFR, and other safety KPIs |
| PPE Tracking | Monitor PPE issuance, condition, and replacement schedules |

**Key entities**: `Incident`, `NearMiss`, `EmployeeHealthRecord`, `SafetyInspection`, `Hazard`, `PPERecord`

---

### 7. Fraud & Incident Reporting
**Purpose**: Enable secure reporting of fraud, misconduct, and other incidents with investigation workflows.

| Feature | Description |
|---|---|
| Fraud & Misconduct Reporting | Structured intake forms for reporting fraud, corruption, or policy violations |
| Anonymous Whistleblowing Portal | Public-facing, anonymous reporting channel with unique case tracking codes |
| Incident Investigation Workflow | Assign investigators, track investigation steps, collect evidence |
| Case Management | Manage cases from intake → investigation → resolution → closure |
| Audit-Ready Reporting | Generate investigation reports suitable for regulators, auditors, and boards |
| Confidentiality Controls | Restrict case access to authorised investigators only |

**Key entities**: `FraudReport`, `WhistleblowCase`, `Investigation`, `InvestigationStep`, `CaseEvidence`

---

### 8. Document & Policy Management
**Purpose**: Centralise all organisational documents, policies, and procedures with version control and approval workflows.

| Feature | Description |
|---|---|
| Secure Document Repository | Organised folder structure for storing policies, procedures, manuals, and records |
| Version Control | Track document revisions — who changed what, when, with diff history |
| Approval Workflows | Configurable multi-step approval chains: draft → review → approve → publish |
| Document Expiry & Review | Set review dates, auto-notify owners when documents are due for review |
| Access Control | Role-based access to documents — view, edit, approve, delete permissions |
| Document Tagging & Search | Tag documents by category, department, standard; full-text search |

**Key entities**: `Document`, `DocumentVersion`, `DocumentApproval`, `DocumentCategory`, `DocumentTag`

---

### 9. Dashboards & Analytics
**Purpose**: Provide real-time visibility into the organisation's GRC posture through interactive dashboards and reports.

| Feature | Description |
|---|---|
| Executive Dashboard | High-level overview for C-suite and board members — risk score, compliance %, open actions |
| Risk Heat Maps | Visual 5×5 (or configurable) heat map showing risk distribution by likelihood and impact |
| Compliance Status Reports | Bar/pie charts showing compliance rates by regulation, department, or time period |
| Audit Performance Indicators | Audit completion rates, finding trends, average closure time |
| Safety Performance | LTIFR, incident trends, inspection completion rates |
| Custom Reports | Build custom reports with filters, date ranges, and export to PDF/Excel |
| Regulatory Reporting | Pre-formatted reports for submission to regulators in banking, telecom, insurance |

**Key entities**: Aggregated views from all modules — no standalone entities.

---

## Cross-Cutting Features

### Security & Access Control
| Feature | Description |
|---|---|
| Data Encryption | 256-bit encryption for data at rest and in transit |
| Role-Based Permissions | Granular permissions: admin, risk manager, auditor, compliance officer, field staff, board member |
| Full Audit Trail | Every user action logged with timestamp, user ID, IP address, and action details |
| Session Management | Secure sessions via Sanctum, configurable timeout |
| Two-Factor Authentication | TOTP-based 2FA via Jetstream |

### Notifications & Alerts
| Feature | Description |
|---|---|
| Email Notifications | Automated emails for assignments, reminders, escalations, and approvals |
| In-App Notifications | Real-time notification bell with unread count |
| Configurable Triggers | Users/admins can configure which events trigger notifications |

### Mobile-Friendly Interface
- Fully responsive design for field inspections, incident reporting, and audit checklists
- Touch-optimised forms and navigation
- Works on any modern browser — no native app required

### Whistleblowing Portal
- **Standalone public page** accessible without authentication
- Anonymous submissions with tracking codes
- Encrypted communication channel between reporter and investigator
- Fully separate from authenticated application for anonymity protection

---

## User Roles (Typical)
| Role | Access |
|---|---|
| **Super Admin** | Full system access, user management, system configuration |
| **Admin** | Organisation-level administration, user management |
| **Risk Manager** | Risk register, risk dashboards, mitigation plans |
| **Compliance Officer** | Compliance register, evidence management, regulatory reports |
| **Lead Auditor** | Audit planning, review, sign-off |
| **Auditor** | Audit execution, checklists, working papers |
| **Safety Officer** | OHS module, inspections, incident reporting |
| **Investigator** | Fraud/incident cases, investigation workflow |
| **Department Manager** | Department-scoped views across modules |
| **Board Member** | Read-only executive dashboards and reports |
| **Field Staff** | Mobile forms: inspections, incident reporting, near-miss logging |

---

## Application Structure (Laravel)
```
app/
├── Models/          # Eloquent models for all entities above
├── Http/
│   ├── Controllers/ # Inertia controllers per module
│   └── Middleware/   # Auth, role-check, audit-logging middleware
├── Policies/        # Authorization policies per model
├── Notifications/   # Email & in-app notification classes
├── Services/        # Business logic services (risk scoring, report generation, etc.)
└── Enums/           # Status enums, severity levels, risk categories

resources/js/
├── Pages/
│   ├── Auth/        # Authentication pages (login, register, etc.)
│   ├── Dashboard/   # Executive and role-based dashboards
│   ├── Risks/       # Risk management screens
│   ├── Compliance/  # Compliance management screens
│   ├── Audits/      # Audit management screens
│   ├── CAPA/        # Corrective action screens
│   ├── OHS/         # Occupational health & safety screens
│   ├── Fraud/       # Fraud & incident reporting screens
│   ├── Documents/   # Document & policy management screens
│   └── Reports/     # Analytics and reporting screens
├── Components/      # Shared UI components
└── Layouts/         # App layout, auth layout

database/migrations/  # All table schemas
database/seeders/     # Demo data and role/permission seeders
```

---

## Key Design Decisions
1. **Inertia.js over API + SPA**: Keeps routing server-side for security, session management, and simplicity — while delivering SPA-like UX
2. **PrimeVue for complex UI**: Data tables, charts, calendars, and form components for enterprise-grade UI needs
3. **Lucide icons**: Consistent, lightweight icon set across the entire application
4. **Module-based structure**: Each GRC module is self-contained with its own pages, controllers, models, and policies
5. **Centralised audit logging**: Middleware-level logging ensures every action across every module is captured
6. **Role-based, not team-based**: Access control is permission-based using roles rather than Jetstream teams
