CO2Calc Architecture Snapshot

Frozen vs Live (Intro)

This page documents a frozen teaching snapshot of CO2Calc for repeatable demos and labs.

The frozen snapshot is intended to stay stable while the live CO2Calc version continues evolving.

Functionality and calculation behavior are intentionally preserved from the snapshot date rather than improved here.

Use this page as a shared reference when discussing architecture, constraints, and human-in-the-loop decisions.

Folder Structure Snippet (Repo)

CO2 Calculator/
├── md/
│   └── CO2Calc — Frozen Teaching Snapshot Tasks.md
├── n8n/
│   ├── Co2Calc_v1_*.json
│   └── Co2Calc_v2_*.json
├── services/
│   ├── co2calc_demo_ui/
│   ├── co2calc_demo_ui_frozen_teaching_snapshot_2026-02-25/
│   │   ├── app/
│   │   │   ├── main.py
│   │   │   └── static/
│   │   │       ├── app.js
│   │   │       ├── architecture-snapshot.html
│   │   │       ├── index.html
│   │   │       └── styles.css
│   │   ├── Dockerfile
│   │   ├── README.md
│   │   └── requirements.txt
│   ├── co2calc_emissions_engine/
│   ├── co2calc_export_ods/
│   └── co2calc_extractor/
└── docs/
    ├── known-limitations.md
    └── spec_excerpt.md

Spec Excerpt (Core Feature + Constraints + AI Permissions)

# Spec Excerpt: Ingest Proxy (Frozen Teaching Snapshot)

Core feature: The Demo UI sends ingest requests to n8n through a backend proxy (`POST /api/ingest`)
to avoid browser CORS issues and keep webhook details server-side.

Constraints
- `pipeline_type` allowed values: `schedule`, `receipt`
- `execution_mode` allowed values: `test`, `prod`
- Required fields: `tenant_id`, `project_id`, `source_file_url`
- Webhook target resolves from explicit `webhook_url` or environment defaults (pipeline + mode)
- UI service forwards request payload to n8n and does not change calculation logic

AI permissions (current snapshot)
- `ai_mode` is limited to `off`, `local`, or `eu` (default: `off`)
- `ai_assisted` defaults to `false`
- Optional AI fields may be forwarded: `ai_model`, `ai_prompt_id`, `ai_processing_location`
- Browser UI does not call AI providers directly; downstream workflows/services decide actual AI usage

Known Limitations (Snippet)

# Known Limitations (Frozen Teaching Snapshot)

- The Demo UI accepts document URLs only; there is no browser file-upload flow.
- Results are not persisted (no database, no job history, no saved user sessions).
- Runtime behavior depends on reachable n8n webhooks and downstream services.
- Demo authentication is an optional shared passcode, not a role-based access system.
- The UI includes technical/operator panels and JSON views intended for demo workflow use.