Emiflow Package Overview¶

See the full API at ferrosoft.apps.emiflow package.

Modules¶

apps

Django application configuration for the emiflow app.

Wires up settings-menu entries (under the Emissions category) and hooks emiflow updater into ferrobase_update management command.

filter

django-filter FilterSet definitions for emiflow list views.

Each FilterSet here backs a corresponding list view: it parses the request query string, validates it against the model fields declared in Meta, and produces a filtered queryset plus a bound form that templates render as the filter sidebar. Custom method filters support filtering by related-object primary key, by membership in a PostgreSQL array column, and by IN clauses for multi-select widgets.

metrics

Prometheus metrics for emiflow tonnage tracking.

Exposes per-tenant tonnage usage and per-organisation tonnage limits so subscription overages can be alerted on and dashboarded.

tables

django-tables2 table classes for emiflow list and detail views.

Each table maps a model (or a flat record produced by an aggregation) to the columns shown in templates, with column types drawn from ferrosoft.apps.ferrobase.tables for shared rendering behaviour (number formatting, action buttons, linkified cells). Tables ending in CRUDTable add an actions column with edit/delete buttons whose delete URL each subclass resolves in get_delete_action_url.

urls

URL configuration for the emiflow application.

Exposes the dashboard index, per-domain CRUD URL bundles imported from ferrosoft.apps.emiflow.views, ad-hoc views for emission intensity, file import, reporting, treatment-operation allocation, and the settings pages, plus the DRF REST API mounted at api/ via ferrosoft.apps.emiflow.api.router.router. The app namespace is emiflow.

widgets

Custom Django form widgets used by emiflow forms and tables.

Subpackages¶

emiflow.api¶

Detail page: ferrosoft.apps.emiflow.api package.

router

emiflow.catalog¶

Detail page: ferrosoft.apps.emiflow.catalog package.

conversion: Import utilities for catalog files.
database

emiflow.models¶

ORM models for the emiflow application.

The package is split into one module per bounded sub-domain:

booking — emission booking records and lifecycle categories (the immutable journal of calculated emissions).
catalog — reference data for emission factors, energy carriers, emitters, and the catalogs they belong to.
dataimport — staging tables for bulk transport import.
intensity — EmissionIntensity shared by transport operations, treatment operations, and emitters.
operation — transport operations (the activity definition reused across chain elements).
reporting — report definitions and report templates.
settings — per-tenant emiflow and Business Central settings.
signals — post-save / post-delete hooks that keep cross-cutting state (allocation, intensity ownership) consistent.
tegos — adapters for inbound data from the TEGOS waste-management ERP.
transport — transport chains, their elements, and freight items.
treatment — treatments, treatment operations, and their input/output lines.

Star-imports below flatten the public names into the package namespace so callers can from ferrosoft.apps.emiflow.models import Treatment without knowing which sub-module a model lives in.

Detail page: ferrosoft.apps.emiflow.models package.

booking

Emission booking records and lifecycle categories.

This module defines the immutable journal of calculated emissions:

EmissionBookingRecord — one row per (lifecycle category, emitting entity, material) triple. Fields are denormalised (material arrays, partner names) so reports can query a single table without joining live operational data.
LifecycleCategory — user-defined categories plus the four predefined ones (treatment, incoming/outgoing transport, drop shipment) enumerated in PredefinedLCC.
LCCValue — abstract base for manually entered per-category emission values that subclasses attach to transports or treatments.

The EmissionBookingRecordQuerySet exposes the aggregations used by the reporting pipeline (totals by entity, by material, by lifecycle category) — all keyed off the denormalised columns so they remain valid even after the originating operation has changed.

catalog

Reference catalog: emitters, energy carriers, and their emission factors.

A EmissionsCatalog is a published bundle of emission data (e.g. the GLEC public extract) with copyright and licence information. Each catalog contains Emitter (vehicles or hub equipment), EnergyCarrier, and EmissionFactor. Models share the shape of the upstream emiflow.json JSON schema so updates can be imported in bulk.

dataimport

Staging models for bulk transport-chain imports.

Rows here represent one input line that the ferrosoft.apps.emiflow.dataimport services then turn into real TransportChain records. SimpleImportLine and MultiLineImportLine differ in whether one row maps to a whole transport chain or to one element of a multi-hop chain; MultiLineBookingRecord tracks which chains a given import job produced so it can post (or roll back) emissions atomically.

intensity

Emission intensity values shared across transport ops, treatment ops, and emitters.

An EmissionIntensity is the calculated gCO2e per tkm (or gCO2e per t for treatments) figure with all of the input variables it was computed from. The owner_type + owner_id pair forms a weak polymorphic reference so the same intensity row can belong to any of the three intensity-capable model classes; cleanup is handled by the post-delete signals in ferrosoft.apps.emiflow.models.signals.

operation

Transport-operation model and its operation-type enum.

A TransportOperation is the activity definition (emitter + energy carrier + activity type) that is reused across one or more transport-chain elements. It owns an EmissionIntensity once calculated.

reporting

Models for emission reports and the templates that render them.

A Report captures the user’s selection (type, filter query string, proportional-emission method); a ReportTemplate captures the visual chrome (logo, preamble, epilogue) reused across generated documents. Logos are inlined as base64 so the rendered HTML can be turned into PDF by WeasyPrint without external fetches.

settings

Per-tenant emiflow configuration models.

Settings is a singleton (created lazily on first read) that holds references to storage directories and the user-defined emissions catalog; TransportChainDefaults keeps default transport-chain attributes per vehicle type; BusinessCentralSettings holds OAuth credentials for the Dynamics 365 Business Central integration.

signals

Cross-model lifecycle hooks for emiflow.

Two concerns are wired up here:

Whenever a treatment-operation output line is inserted or removed, the parent operation’s allocation is recomputed (no-op under manual allocation).
Whenever an entity that owns an EmissionIntensity (transport operation, treatment operation, or emitter) is deleted, the matching intensity row is removed. The intensity table uses a weak (owner_type, owner_id) reference rather than a real foreign key, so this cascade must be driven explicitly from signals.

The module is loaded via the wildcard import in ferrosoft.apps.emiflow.models.__init__, which is what registers these receivers at app startup.

tegos

In-memory value objects used by the TEGOS waste-management ERP adapter.

These types are not Django models — they carry data parsed out of TEGOS order documents while transport chains and freight items are being constructed. They live next to the persistent models because they share domain vocabulary (posting types, materials, weights).

transport

Transport-chain domain models.

A TransportChain is one consignment from consignor to consignee broken into ordered TransportChainElement (TCE) hops. Each TCE points at a reusable TransportOperation (the activity definition) and may carry geo-points for shortest-feasible or great- circle distance calculations. The chain’s freight is described by FreightItem rows (material + weight). Custom per-lifecycle emissions are attached via TransportLCCValue.

treatment

Treatment and treatment-operation domain models.

A TreatmentOperation is the recipe: what materials go in, what comes out, which emitter and energy carrier are involved, and how emissions should be allocated to the outputs (by weight or manually). A Treatment is a specific application of that recipe on a booking date, with its own input/output lines that can deviate from the operation defaults. Operations are certified before they can be referenced; certifying enforces that emission intensity is set and output allocations sum to 100 %.

emiflow.services¶

Service layer for the emiflow application.

This package holds the fat services / thin views business logic for emission calculation, reporting, integration, and supporting concerns:

builder — fluent builders that compose TransportChains and their related rows.
businesscentral — adapters for the Microsoft Dynamics 365 Business Central connector.
emissions — transport-chain emission calculator and booking service.
geographic — strategy for resolving activity distance by distance type.
pcf — product carbon footprint roll-up across all chains carrying a material.
reporting — document generators that turn booking records into renderable reports.
session — per-request storage of the current transport chain in the user session.
tonnage — per-tenant / per-organisation tonnage queries used for subscription accounting.
treatment — treatment emission calculator and booking service.
update — periodic update hooks that seed predefined lifecycle categories per tenant.
vehicle — heuristic that guesses a VehicleType from freight weight.
visitor — visitor implementations executed against TransportChain walks (debug printer, geocoding/routing).

Detail page: ferrosoft.apps.emiflow.services package.

builder

Fluent builders for assembling transport chains and related rows.

Each ModelBuilder subclass wraps a Django model instance and exposes chainable setter methods so that complex transport chains can be constructed declaratively. Builders compose via BuilderOfBuilders (a chain holds builders for its elements and freight items), and can either save() rows one-by-one or defer everything into a BulkCreator for one bulk upsert per model class.

emissions

Transport-chain emission calculation and booking.

This module is the heart of the transport-side emiflow pipeline:

TransportChainCalculator walks a chain’s elements, looks up each operation’s emission intensity, and produces per-element and per-chain results (transport activity, distance, emissions for the operation and energy provision categories).
EmissionIntensityCalculator derives a new emission intensity from raw inputs (factor, fuel quantity, mass, distance), performing unit normalisation so callers can supply values in any supported unit.
TransportBookingService posts a chain: it geocodes points, computes emissions, denormalises everything into EmissionBookingRecord rows (one per chain + one per TransportLCCValue), and flips the chain status to POSTED.

ISO 14083 terminology is used throughout: TCE = Transport Chain Element, transport activity = mass × distance (tkm), intensity = emission / activity.

geographic

Strategy that resolves activity distance from a TCE’s distance type.

For actual distance the user-entered value is treated as authoritative. For great-circle (GCD) and shortest-feasible (SFD) distances the configured router computes the distance between origin and destination geo-points. Results are normalised to kilometres.

pcf

Product Carbon Footprint (PCF) calculation across all chains for a material.

The ProductCarbonFootprintService aggregates transport emissions for every TransportChain that carries a given Material, normalises units across chains, and reports the emission-per-tonne intensity in kgCO2e.

reporting

Document generators that turn booking records into renderable reports.

Each DocumentGenerator subclass binds a Report (and its filtered queryset of booking records) to a list of DocumentOutput objects. The base generate() renders each output’s template into HTML, and prepare_report_models() persists the rendered HTML as short-lived StoredFile-backed reports that can later be turned into PDF by the upstream reporting service.

DocumentGeneratorRegistry maps ReportType values to the matching generator class.

session

Per-user-session storage of the current transport chain.

When the user is mid-way through editing a transport chain across multiple views, the chain’s primary key is stashed in the Django session so subsequent views can resume without it being passed through every URL. All helpers degrade silently when the request has no session (e.g. during management commands or unit tests).

tonnage

Tonnage accounting for subscription billing.

Customers are billed on the cumulative weight of (non-simulation) emission bookings. This module exposes two query paths:

A direct database aggregate per tenant (TonnageService.get_summary()) used at startup to seed the Prometheus counter and on demand for reconciliation. Expensive — it opens a connection to every active tenant database.
A cheap VictoriaMetrics query (TonnageServiceVictoria.get_org_stats()) that returns the rolling 4-week tonnage and configured limit per organisation from the metrics store.

treatment

Emission calculation and booking for treatments.

TreatmentEmissionCalculator multiplies the treatment’s output mass by the operation’s emission intensity (for both operation and energy provision categories) to derive the total emission. TreatmentBookingService then splits that total across output lines using each line’s allocated_fraction and creates one EmissionBookingRecord per output and per attached TreatmentLCCValue.

update

Emiflow hooks into the ferrobase update pipeline.

The ferrobase ferrobase_update management command iterates over registered global and per-tenant updaters at deploy time. This module registers an updater that ensures the four predefined LifecycleCategory rows exist in every database — both the shared catalog database (global pass) and each tenant database (tenant pass).

vehicle

Heuristic mapping from freight weight to a likely VehicleType.

Used during bulk import when the source data does not specify the vehicle type explicitly. The thresholds are hard-coded approximations and will likely become tenant-configurable.

visitor

Visitor implementations driven by TransportChain.accept().

Visitors here perform actions over an entire chain’s structure (elements, freight items, geo-points). DebuggerVisitor dumps every field to stdout for development; GeocodingRoutingVisitor populates missing coordinates and activity distances before emission calculation.