Skip to content

ESG Specification

Welcome to the comprehensive documentation for the implementation-ready ESG (Environmental, Social, and Governance) reporting platform built on Laravel.

Overview

This documentation provides a complete, implementation-ready specification for an ESG data collection, validation, review, approval, and reporting system. The platform is designed for:

  • Multi-tenant architecture with hard tenant isolation
  • Offline-first mobile data collection for field collectors
  • Comprehensive RBAC with segregation of duties
  • GRI Standards 2021 compliance with support for custom KPIs
  • Audit-first design with immutable data and full traceability
  • Laravel backend with queue-based processing and validation

Documentation Size: ~380KB across 26 files Status: Implementation-ready with Laravel code examples, migrations, API contracts, and acceptance criteria

Quick Start

For Product Managers

  1. Read docs-gap-report.md - Understand what's covered and what's implementation-ready
  2. Review ESG Domain Glossary - Learn ESG terminology
  3. Explore GRI/ESG Scope v1 - Understand reporting framework coverage

For Backend Developers

  1. Start with Complete Data Model - Database schema and migrations
  2. Review API Overview → Collector API → Admin API
  3. Implement Validation Engine and Ingestion Pipeline
  4. Follow Testing Strategy for TDD approach

For Frontend Developers

  1. Review Collector API - Mobile app endpoints
  2. Review Admin API - Web dashboard endpoints
  3. Understand Collector Workflow - Offline-first sync mechanics
  4. Implement based on Error Handling standards

For Security/Compliance Teams

  1. Review RBAC Matrix - Permission model
  2. Read Laravel RBAC Implementation - Security patterns
  3. Assess Security & Compliance - Encryption, PII, threats

Documentation Structure

📘 Concepts & Fundamentals

  • ESG Domain Glossary - Authoritative definitions for all ESG, sustainability, and reporting terms (materiality, disclosure, baseline, etc.)
  • Reporting Concepts - Organizational boundaries, consolidation approaches, baselines, restatements (GRI 2-2 compliant)

📋 Scope & Standards

  • GRI/ESG Scope v1 - GRI Standards 2021 coverage (Universal + Environmental + Social + Governance)
  • Standards & Framework Metadata - Database schema for frameworks, standards, disclosures (GRI → ISSB/TCFD mapping)
  • Metric Catalog - Comprehensive metric metadata schema, validation rules, calculation methods, sensitivity classification

🏗️ Architecture

🔄 Workflows

  • Collector Workflow - NEW - Offline-first data collection, draft → queue → upload → feedback loop
  • Ingestion Pipeline - NEW - Idempotent ingestion, deduplication, retry logic, error recovery
  • Validation Engine - NEW - 6 validation types (schema, domain, referential, evidence, business, anomaly)
  • Review & Approval - NEW - Task assignment, SLA tracking, segregation of duties, approval workflows
  • Locking & Restatements - NEW - Period locking, content hashing, restatement process (GRI 2-4 compliant)

🌐 API Specifications

  • API Overview - NEW - Authentication (JWT), versioning, pagination, rate limiting, idempotency
  • Collector API - NEW - Mobile/field endpoints (templates, submissions, evidence, sync)
  • Admin API - NEW - Dashboard endpoints (review, approve, period management, reports, audit logs)
  • Error Handling - NEW - Standard error model, HTTP status codes, error codes (AUTH_, VALIDATION_, RESOURCE_, STATE_)

💾 Data Management

  • Data Lifecycle - 8-state machine (Draft → Queued → Received → Validated → Rejected → Processed → Approved → Locked)
  • Evidence Management - NEW - File handling, virus scanning, storage (S3), retention, chain-of-custody

📊 Reporting

  • Report Outputs - NEW - Report types (GRI, summaries, exports), generation pipeline, versioning (draft/final/restated)

🔒 Security

🧪 Development

  • Testing Strategy - NEW - Test pyramid (70% unit, 20% feature), audit log invariants, fixtures, CI/CD

Key Features

Audit-First Design

  • ✅ Immutable Submissions: Data never edited after submission (new versions created)
  • ✅ Append-Only Audit Logs: Every state transition logged with actor, timestamp, before/after state
  • ✅ Content Hashing: SHA-256 hashes for locked periods and evidence files
  • ✅ Chain-of-Custody: Full traceability from metric → submission → evidence → approval

Offline-First Mobile

  • ✅ Draft Storage: Client-side SQLite for offline editing
  • ✅ Queue Synchronization: Automatic upload when online, retry with exponential backoff
  • ✅ Idempotency: UUID-based deduplication prevents duplicate submissions
  • ✅ Feedback Loop: Sync API returns validation errors and reviewer comments

Comprehensive Validation

  • ✅ 6 Validation Types: Schema, domain, referential, evidence, business rule, anomaly detection
  • ✅ Field-Level Errors: Structured error responses for collectors
  • ✅ Async Processing: Queue jobs for validation and processing
  • ✅ Configurable Rules: JSONB-stored rules per metric definition

Segregation of Duties

  • ✅ No Self-Approval: Collectors cannot approve own submissions (enforced by policy)
  • ✅ Role Separation: Collectors ≠ Reviewers ≠ Approvers (RBAC gates)
  • ✅ Admin Oversight: Admin approvals flagged in audit log
  • ✅ Auditor Read-Only: External auditors have full read access, zero write access

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

  • Database migrations (complete data model)
  • RBAC setup (policies, gates, middleware)
  • Metric catalog seeder (GRI Standards 2021)
  • Authentication (JWT, refresh tokens)

Phase 2: APIs (Week 2-3)

  • Collector API (templates, submissions, evidence, sync)
  • Admin API (review, approve, period management)
  • Error handling middleware
  • Rate limiting

Phase 3: Workflows (Week 3-5)

  • Ingestion pipeline (idempotency, queues)
  • Validation engine (all 6 rule types)
  • Review/approval workflow (task assignment, SLA)
  • Locking/restatements (content hashing)

Phase 4: Reporting (Week 5-6)

  • Report generation (PDF, XLSX, JSON exports)
  • GRI disclosure templates
  • Audit package generation

Phase 5: Production Readiness (Week 6-7)

  • Security hardening (encryption, secrets, PII)
  • Performance optimization (indexes, caching, query tuning)
  • Monitoring (CloudWatch, Prometheus, alerts)
  • Backups & DR (RDS Multi-AZ, S3 replication)

Cross-Cutting Concerns

Multi-Tenancy

Every API request, database query, and file storage operation is scoped by tenant_id. Middleware enforces tenant context, preventing cross-tenant data leakage.

Auditability

Every mutation creates an audit log entry. Audit logs are immutable (no updated_at column) and cryptographically sealed for compliance.

Immutability

Submissions, evidence files, and locked reporting periods are immutable. Corrections create new versions with full audit trail.

Technology Stack

Component Technology Purpose
Backend API Laravel 10+ (PHP 8.2+) REST API, queue jobs, RBAC
Database PostgreSQL 15+ Multi-tenant data with JSONB support
Queue Redis + Laravel Horizon Async validation, processing, reporting
Storage AWS S3 Evidence files (encrypted at rest)
Auth Laravel Sanctum (JWT) API authentication, token refresh
Monitoring CloudWatch + Prometheus Metrics, logs, alerts
CI/CD GitHub Actions Automated tests, deployments

Additional Resources

Contributing

This documentation is a living specification. To contribute:

  1. Propose changes via pull request
  2. Follow the template in each doc (Purpose, Scope, Key Decisions, Laravel Implementation, Acceptance Criteria)
  3. Update cross-references when adding/modifying sections
  4. Increment version numbers in Change Log

License

Please refer to the repository for license information.

Last Updated: 2026-01-03 Documentation Version: 2.0 (Implementation-Ready Expansion) Total Pages: 26 files (~380KB)