CELINE Nudging Tool

Backend service that transforms Digital Twin events into personalized push notifications for renewable energy community participants.

Event Flow

DigitalTwinEvent -> Engine -> Orchestrator -> Publisher (web push)

Engine — evaluates rules against the incoming event, selects matching nudge type and severity, renders a Jinja2 message template
Orchestrator — applies delivery policies (suppression, deduplication, frequency limits, user preferences)
Publisher — sends the notification via the registered delivery channel (currently: web via VAPID web push)

Rule-based engine with YAML-seeded rules, templates, and preferences
Delivery suppression and deduplication (daily / weekly / monthly / yearly scopes)
Web push (VAPID) via pywebpush
Configurable per-user notification preferences
PostgreSQL persistence via SQLAlchemy async

Docker (recommended):

docker compose up --build

Starts: db (PostgreSQL on port 5433), initdb (schema + seed), api (port 8000).

Local Python:

uv sync
python -m db.init_db        # create schema and seed data
hypercorn api.main:app --bind 0.0.0.0:8000

Variable	Description	Default
`DATABASE_URL`	PostgreSQL async URL	required
`DEFAULT_LANG`	Default notification language	`en`
`MAX_PER_DAY_DEFAULT`	Default max notifications per day	`3`
`VAPID_PUBLIC_KEY`	VAPID public key (base64url)	required
`VAPID_PRIVATE_KEY`	VAPID private key (base64url)	required
`VAPID_SUBJECT`	VAPID contact (mailto: or https:)	required

Document	Description
Architecture	Event flow, engine/orchestrator/publisher components, database models
Engine	Rule evaluation, NudgeType/Severity, Jinja2 templates, dedup scopes, YAML seed format
API Reference	All endpoints: ingest-event, webpush, notifications, preferences
Development	Local setup, VAPID key generation, seed management, running tests