Skip to content

CRD — co2-calculator (Code Requirements Document)

This document fixes the project's intent, scope, and decision trail. Treat it as authoritative when other docs disagree.

1. WHY — the business problem

EPFL labs must report annual CO2 emissions across travel, infrastructure, equipment, purchases, and shared services. Spreadsheets do not scale, hide assumptions, and cannot be audited.

The co2-calculator gives each lab a single, secure, multilingual web app to enter activity data, apply curated emission factors, and produce auditable footprints. Other academic institutions must be able to reuse the codebase.

2. WHAT — scope

In-scope deliverables.

  • Custom web application matching EPFL IT standards and branding.
  • Modules: laboratory profile, professional travel, infrastructure, equipment energy, purchases, internal services, results visualisation.
  • Manual CSV import with validation; optional automated ingestion (lab energy, staff directory).
  • Backoffice tooling: emission-factor management, job history, sync progress, audit logs, role and permission administration.
  • REST API documented with OpenAPI; PDF and CSV exports.
  • Docker-based deployment to the EPFL XaaS Kubernetes platform.

Out-of-scope.

  • Real-time IoT ingestion of building meters.
  • Public-facing emission dashboards beyond authenticated EPFL users.
  • Financial accounting or scope-3 supply-chain analytics outside listed modules.
  • AI-driven assumption inference (tracked as an optional future extension).

Constraints.

  • EPFL IT and security standards (Annexe 8). HERMES project methodology.
  • Production target: Q2 2026. Open-source under GPL-3.0.

3. HOW — high-level architecture

See System Overview for the canonical diagrams (ingress, frontend pods, FastAPI backend, PostgreSQL, S3, Entra ID).

The stack is Vue 3 + Quasar on the frontend, FastAPI on the backend, in-process async jobs (asyncio, no broker), PostgreSQL behind PgBouncer for persistence, and EPFL S3 for object storage. Authentication runs through Microsoft Entra ID via OIDC.

4. Decisions trail

Each architecturally meaningful decision is captured as an ADR. Add a new ADR before changing any of these.

ADRs 011 and 015 are reserved for in-flight decisions; link them here once their files land in architecture-decision-records/.

5. Roles

The system recognises four actor classes, mapped to Entra ID groups and faculty scopes.

  • Data-entry user — lab member who records activity (travel, equipment, purchases) for their unit.
  • Validator — lab manager (Utilisateur·rice principal·e) who reviews, corrects, and signs off annual data.
  • Backoffice operator — Gestionnaire Métier who curates emission factors, runs imports, and audits cross-unit data; permissions scope to a sub-perimeter (see issue #459).
  • Admin — Gestionnaire IT with full operational access: user roles, system jobs, retention, and platform configuration.

Role assignment and faculty filtering are enforced server-side; see ADR-005.

6. Data integration

Inputs.

  • User-entered forms per module.
  • CSV uploads validated against schemas; rejected rows surface as actionable errors.
  • Curated emission-factor datasets (ADEME, DEFRA, custom) ingested via background jobs.
  • EPFL Accred for user–unit linkage; staff directory for headcount.

Outputs.

  • REST/JSON API for the SPA and external consumers (OpenAPI documented).
  • PDF and CSV exports of footprints and breakdowns.
  • Externalised application logs with 1–10 year retention.

7. Source of truth

When in doubt, this CRD wins. For deeper detail follow these links.