Breathe ESG — Compliance-Grade Data Ingestion & Review Platform

Breathe ESG is a production-quality enterprise staging and auditing platform engineered to ingest, normalize, verify, and lock heterogeneous ESG (Environmental, Social, and Governance) data. Built using a robust multi-tenant staging architecture, it bridges the gap between raw, messy data uploads (from utility portals, travel expense systems, and ERP fuel exports) and audit-ready public reporting.

---

🛠 Technology Stack

• Backend: Django 4.x + Django REST Framework (DRF) + SQLite (for development) / PostgreSQL (production-ready)
• Frontend: React 18 + Vite + Custom CSS Modules (Obsidian ESG Dark Theme)
• Design Systems: CSS variables, responsive grid systems, micro-animations, glassmorphism, and Lucide React icons
• Deployment Assets: Vercel SPA routing (vercel.json) & Railway config (railway.toml, Procfile)

---

🏗 Key Features & Capabilities

1. Multi-Tenant Data Isolation: Real row-level database partitioning scoped to tenants (like the seeded Demo Corp).
2. Immutable Data Provenance (RawRecord): Raw file records are kept append-only and untouched in their original state. If normalization rules update, we can re-process historical raw inputs.
3. Greenhouse Gas Normalization Service: Ingests heterogeneous data units and normalizes them into standardized $CO_2e$ values in kilograms:
   • Scope 1 (SAP Fuel Export): Converted from Liters (L) or Gallons (GAL) using direct combustion factors.
   • Scope 2 (Utility Electricity): Normalizes kWh, MWh, and commercial/industrial utility tariff codes.
   • Scope 3 (Concur Travel Expense): Calculates carbon footprint for short, medium, and long-haul flights ($CO_2e$ factors relative to distance), hotel nights, and car rental mileage.
4. Compliance-Grade State Machine: Records transition through a strict transactional flow: Pending ➔ Approved (Locked) or Rejected (requires a mandatory explanation audit note).
5. Compliant Audit Trails (AuditEvent): Logs immutable ledger entries capturing who, when, and what changed on every record.
6. Automated Flagging & Verifications: Detects data anomalies during ingestion (such as chronological inversions, negative volumes, missing plant codes, or massive industrial outliers).
7. Excel-Compatible CSV Exporter: Exposes an on-demand download button on the dashboard to export currently filtered views with human-readable site and route translation details.

---

📂 Project Architecture

breathe-esg/
  ├── backend/               # Django REST API application
  │    ├── config/           # URL mapping, middleware, WSGI, ASGI
  │    ├── tenants/          # Tenant model and db schemas
  │    ├── ingestion/        # CSV parsers (SAP, Utility, Travel), DataSource models
  │    ├── normalization/    # Carbon conversion formulas and heuristics
  │    ├── review/           # NormalizedRecord model, transitions, tests
  │    ├── audit/            # AuditEvent compliance logging
  │    └── api/              # DRF views, serializers, routes
  │
  ├── frontend/              # Vite + React Client application
  │    ├── public/           # Static icons and assets
  │    └── src/
  │         ├── api/         # Axios REST client endpoints
  │         ├── components/  # Reusable widgets (Navbar, StatusBadge, AuditTrail)
  │         ├── pages/       # UploadPage, DashboardPage, RecordDetailPage
  │         ├── App.jsx      # React Router routing map
  │         └── index.css    # Obsidian ESG global styling theme
  │
  ├── sample_data/           # Curated CSV files for E2E verification
  │    ├── sap_fuel_sample.csv
  │    ├── utility_electricity_sample.csv
  │    └── travel_sample.csv
  │
  └── *.md                   # Deep-dive architecture documentation

---

🚀 Quick Start Guide

Prerequisites

• Python 3.11+
• Node.js 18+ & npm

---

Step 1: Spin Up the Django Backend

1. Navigate to the backend directory and set up a virtual environment:

   cd backend
   python3 -m venv venv
   source venv/bin/activate

2. Install Python packages:

   pip install -r requirements.txt

3. Run database migrations: (This automatically seeds the SQLite database with the default Demo Corp tenant, standard DataSources, and the analyst superuser)

   python manage.py migrate

4. Start the local server:

   python manage.py runserver

   The backend will start running on http://127.0.0.1:8000/.

---

Step 2: Spin Up the React Frontend

1. Navigate to the frontend directory:

   cd ../frontend

2. Install npm dependencies:

   npm install

3. Boot up the Vite dev server:

   npm run dev

   Open your browser and navigate to http://localhost:5173. You can log in using the credentials:
   • Username: analyst
   • Password: breathe2024

---

🧪 E2E Validation Flow & Testing

1. Ingestion Testing

Go to the Upload Data tab (http://localhost:5173/upload) and process the provided files inside the sample_data/ folder:

• Upload sap_fuel_sample.csv under the SAP Fuel Export source.
• Upload utility_electricity_sample.csv under the Utility Electricity portal source.
• Upload travel_sample.csv under the Concur Expense report source.

2. Verify Flagging Anomalies

Navigate to the Dashboard (http://localhost:5173/dashboard). You will notice records displaying red warning flags. Hover over them to inspect real-time anomaly reasons, such as:

• Negative consumption values or chronological end-date inversions.
• Missing vital parameters (like missing SAP Plant Codes).
• Outlier thresholds (e.g. extremely high single utility spikes).

3. State Machine & Audit Inspection

• Open a pending record to view the Dual-Pane Provenance Inspector (which juxtaposes normalized calculations side-by-side with raw, write-locked CSV properties).
• Submit an Approval to see the record lock down permanently (showing a lock badge).
• Submit a Rejection and note that the system enforces an analyst review explanation which is immortalized in the audit log at the bottom.

4. Excel CSV Export

Apply dashboard filters (e.g., search for specific routes or filter by flagged/unflagged statuses) and click the Export CSV button in the toolbar to download a clean, spreadsheet-ready report.

5. Automated Backend Tests

Run the Django integration test suite locally to verify the state machine constraints and mathematical parsers:

cd backend
python manage.py test

---

📚 Supporting Architectural Documentation

For an in-depth review of the engineering decisions behind Breathe ESG, please check out the following files:

• 📁 MODEL.md: Conceptual definitions of the relational schema, tenant scopes, and stages.
• 📁 DECISIONS.md: Key technical decisions (like Raw vs. Normalized separation and sync-only transactions).
• 📁 TRADEOFFS.md: Analysis of current technical limits, performance profiles, and future scaling plans.
• 📁 SOURCES.md: Industry standards and open libraries referenced during implementation.