Data Architecture
OffGridFlow uses a single canonical data model with strict tenant isolation. Every record traces back to its source through an immutable audit chain.
End-to-End Traceability Chain
Every compliance output can be traced back through this chain to the original activity data.
1
ActivityRaw data point (e.g., 10,000 kWh electricity in US-WEST for January 2026)
2
Emission FactorEPA eGRID 2023 US-WEST: 0.298 kg CO2e/kWh
3
Calculation Ledger10,000 × 0.298 = 2,980 kg CO2e = 2.98 tonnes CO2e. Formula, factor ID, source, region, user, timestamp recorded.
4
Factor SnapshotFactor 0.298 locked to reporting period Jan-Dec 2026. Immutable.
5
Compliance Report2.98 tCO2e included in Scope 2 total for SEC Climate Disclosure 2026.
6
Approval WorkflowReport prepared by operator, reviewed by manager, approved by CFO. Each step timestamped.
7
Export + ChecksumPDF exported with SHA256 checksum. Reconciliation verifies export matches current data.
Entity Definitions
Core tables in the OffGridFlow data model. All tables are tenant-scoped — one tenant cannot access another's data.
Tenant (Organization)Multi-tenant root. Every record is scoped to a tenant. One tenant cannot see or affect another.
id (UUID)nameslugplan (audit_prep | compliance_pro | enterprise)is_activecreated_at
UserAuthenticated account within a tenant. Roles control access.
id (UUID)tenant_id (FK → Tenant)emailpassword_hash (bcrypt)role (admin | user | viewer)mfa_enabledlast_login_at
ActivityA single emissions data point — the atomic unit of carbon accounting.
id (UUID)tenant_id (FK)source (csv | aws | azure | gcp | sap)category (electricity | natural_gas | diesel | ...)scope (1 | 2 | 3)quantityunit (kWh | L | km | ...)activity_datelocationmeter_id
Emission FactorConversion factor from activity quantity to kg CO2e. Sourced from EPA, IEA, DEFRA, IPCC.
id (UUID)scoperegionsourcecategoryunitvalue_kg_co2e_per_unitdata_source (EPA eGRID | IEA | DEFRA | IPCC)yearvalid_fromvalid_touncertainty_%version
Calculation LedgerImmutable record of every emissions calculation. Cannot be modified after creation.
id (UUID)tenant_id (FK)activity_id (FK → Activity)scopequantityunitfactor_idfactor_value (frozen copy)factor_sourcefactor_regionmethodformula (human-readable)result_kg_co2eresult_tonnes_co2ecalculated_by (FK → User)calculated_atis_lockedversionsupersedes_id
Factor SnapshotA locked set of emission factors for a reporting period. Ensures reproducibility.
id (UUID)tenant_id (FK)reporting_period_startreporting_period_endsnapshot_namefactors (JSONB — frozen copies)factor_countstatus (draft | locked | superseded)locked_by (FK → User)locked_at
Compliance ReportGenerated compliance output for a specific framework and year.
id (UUID)tenant_id (FK)report_type (csrd | sec | california | cbam | ifrs_s2)report_yearstatus (draft | in_review | approved | submitted)scope1_emissionsscope2_emissionsscope3_emissionstotal_emissions_co2egenerated_by (FK → User)approved_by (FK → User)approved_at
Approval WorkflowTracks review and approval state for reportable entities.
id (UUID)tenant_id (FK)entity_type (report | inventory)entity_id (FK)status (draft | submitted | reviewed | approved | rejected)prepared_byreviewed_byapproved_byrejection_reasontimestamps for each state
Audit LogImmutable event trail. Every significant action is recorded with actor attribution.
id (UUID)tenant_id (FK)user_id (FK)event_typeaction (create | update | delete | approve | reject)resource_typeresource_idchanges (JSONB before/after)ip_addressuser_agentcreated_at
Change LogField-level modification history for data governance and forensic review.
id (UUID)tenant_id (FK)entity_typeentity_idactionfield_nameold_valuenew_valuechanged_by (FK → User)changed_at
Key Relationships
| From | To | Relationship | Constraint |
|---|---|---|---|
| Activity | Tenant | belongs to | CASCADE delete |
| Activity | Calculation Ledger | calculated by | FK activity_id |
| Calculation Ledger | Factor Snapshot | uses factors from | FK factor_snapshot_id |
| Calculation Ledger | User | calculated by | FK calculated_by |
| Compliance Report | Tenant | belongs to | CASCADE delete |
| Compliance Report | User | generated / approved by | FK generated_by, approved_by |
| Approval Workflow | Compliance Report | governs | FK entity_id |
| Audit Log | Tenant + User | records actions by | FK tenant_id, user_id |
| Change Log | any entity | tracks field changes | entity_type + entity_id |
| Factor Snapshot | Tenant | belongs to | CASCADE delete, UNIQUE per period |
Tenant Isolation
Every database query includes a tenant filter (WHERE tenant_id = $1). This is enforced at the application layer through middleware that extracts the tenant ID from the authenticated JWT session. There is no admin endpoint that can query across tenants. Soft deletes use deleted_at timestamps, and unique constraints include the WHERE deleted_at IS NULL predicate to prevent namespace collisions.