Engineer Flow is een diagnoseplatform voor zware voertuigen en mixer-opbouwen. De actieve app-flow gebruikt nu een deterministische TypeScript-kern voor symptoommapping, constraint-handhaving, failure-mode scoring, guided flows en audit trail.
Belangrijk:
- EFL core beslist, AI niet
- Canonieke JSON-datasets zijn de bron van waarheid
- De kritieke diagnosepad werkt lokaal/offline
- Elke run levert DDS-output + audit trail
De repo bevat daarnaast nog de oudere LUCID/FastAPI-backend en enkele AI-hulppaden, maar de actieve diagnoseflow in de Next.js-app loopt via src/efl_core.
Ontwikkelstatus: de kernflow en server-authenticatie zijn actief in ontwikkeling. Cases en diagnoses ondersteunen duurzame PostgreSQL-opslag via de FastAPI-backend; zonder backendconfiguratie blijft alleen de development-opslag beschikbaar.
De interface is opgebouwd uit één set thematokens in src/app/globals.css (:root = licht,
.dark = diep staal) met een stilstaand blueprint-raster als achtergrond. Ontwerpprincipes:
- Eén accent: staal-cyaan is de actiekleur; veiligheidsamber alleen voor waarschuwing en aandacht.
- Rust door maatvoering: elke pagina gebruikt
.page-shell(vaste marge en breedte); kaarten, knoppen en tabellen hebben één vaste, compacte maat. - Licht is de maatstaf: beide thema's halen WCAG AA (4,5:1) voor tekst. De waarden zijn per tokenduo doorgemeten, niet geschat; de tabel staat in de commit van de opmaakronde.
- Het thema volgt het systeem. Rechtsboven wisselt de schakelaar systeem → licht → donker; in Instellingen → Uiterlijk staat dezelfde keuze als segmented bediening.
Beweging is overal optioneel: de achtergrond staat stil en animaties mogen wegvallen.
- Engineer Flow Vision & Roadmap
- Wat Dit Project Doet
- Huidige Status
- Architectuur
- Vormgeving
- Deterministische Diagnosekern
- Projectstructuur
- Quickstart (Aanbevolen)
- Handmatige Setup
- Configuratie (.env)
- JWT Rollen En Scopes
- API Overzicht
- Belangrijkste Flows
- LUCID Trigger Enforcement
- Datamodel (PostgreSQL)
- Tests
- Troubleshooting
- Production Notes
De volledige productvisie, huidige status, doelarchitectuur, roadmap, productiechecklists en release gates staan in docs/ENGINEER_FLOW_VISION.md.
Engineer Flow zet vrije symptoomtekst om naar:
- canonieke
DESmatches - canonieke
TSevidence - constraint-gefilterde failure modes
- guided diagnoseflows
- DDS v1.0 case-output
- audit trail met
execution_signature
De app bevat daarnaast workflow-functies voor:
- opgeslagen diagnoses
- werkbonnen
- facturatie
- grootboekposten
Actief in het diagnosepad:
src/efl_core/engine.tssrc/efl_core/symptom_bridge.tssrc/efl_core/data/*.jsonsrc/app/api/efl-core/diagnose/route.tssrc/app/actions.ts
Belangrijke eigenschappen:
- hard constraint filtering op failure modes en componenten
- expliciete
knowledge_gapfallback - expliciete
clarification_requiredtoestand bij ambigue invoer - hash-geketende lokale auditopslag in
.efl_store/diagnosis_audit.jsonl - browser-side offline auditbuffering via IndexedDB met sync naar
/api/efl-core/audit/sync - server-side lucid mirror replay via
/api/efl-core/audit/flush - lokale fallback voor expert-chat en case-title als AI niet beschikbaar is
Drie partijen met expliciete rechten:
- Garage: volledige lokale toegang tot ruwe foutcodes en reparatiehistorie.
- Fabrikant: alleen geanonimiseerde patroondata via batch (Trigger 1).
- Verzekeraar: alleen claim-gebonden onderhoudshistorie, exactly-once per claim (Trigger 2).
Alle aanvragen lopen via een manifest (POST /data/opvragen) en worden vastgelegd in:
manifest_requestspolicy_decisionsaudit_events
- Framework: FastAPI
- ORM/Migraties: SQLAlchemy 2 + Alembic
- Database: PostgreSQL
- Auth: JWT RS256 (
kid-based key selectie) - Entry point:
lucid_engineer_flow:app
- Framework: Next.js 15 + React 18 + Tailwind
- Dev server:
npm run devop poort9002
- Primary engine:
src/efl_core/engine.ts - Symptom bridge:
src/efl_core/symptom_bridge.ts - Offline fallbacks:
src/efl_core/offline_assist.ts - API adapter:
src/app/api/efl-core/* - Health endpoint:
src/app/api/efl-core/health/route.ts
- Partij in request body wordt niet vertrouwd.
party_typewordt altijd afgeleid uit JWT claims.src/ai/flows/diagnose-flow.tsis alleen nog een deprecated compatibility layer en mag niet als actief diagnosepad worden gebruikt.
De actieve route is:
-
Vrije tekst ->
DESmatching
src/efl_core/symptom_bridge.ts -
DES -> TSscoring
Formule:((strength * 0.7) + (uniqueness * 0.3)) / 5 -
Subsystem- en clusterselectie
src/efl_core/engine.ts -
Constraint enforcement
constraints.json,electrical_constraints.json,hydraulic_constraints.json,variant_constraints.json,logic_rules.json -
Failure-mode scoring
deterministisch op basis vanTS, subsystemsupport, componentrelaties en constraint-hits -
Guided flow + DDS + audit trail
opgenomen in de diagnose-response -
Browser-side audit buffering + sync
IndexedDB queue ->/api/efl-core/audit/sync-> append-only JSONL + lucid-compatible mirror -
Server-side durable sink replay
.efl_store/lucid_audit_mirror.jsonl+.efl_store/lucid_audit_forward_status.jsonl->/api/efl-core/audit/flush
Canonieke datasets:
master_symptom_set.v1.0.jsondes_ts_map.v1.0.jsonef_diagnostic_schema.jsonversion_manifest.json- component-, failure-mode-, cluster- en constraintbestanden in
src/efl_core/data/
.
├── src/
│ ├── app/ # Next.js app + API routes
│ ├── components/ # UI componenten
│ ├── efl_core/ # Deterministische diagnosekern
│ │ ├── engine.ts
│ │ ├── symptom_bridge.ts
│ │ ├── offline_assist.ts
│ │ ├── data.ts
│ │ ├── types.ts
│ │ ├── version.ts
│ │ └── data/
│ ├── lib/api/ # Frontend API client + types
│ └── ai/ # Legacy/UX AI flows
├── lucid_backend/
│ ├── main.py # FastAPI routes
│ ├── policy.py # Trigger/policy enforcement + reason codes
│ ├── models.py # SQLAlchemy modellen
│ ├── services.py # Domeinservices + seed data
│ ├── security.py # JWT decode/validate + dev token minting
│ ├── audit.py # Manifest/decision/audit registratie
│ └── schemas.py # Request/response modellen
├── alembic/
│ ├── env.py
│ └── versions/ # DB migraties
├── lucid_engineer_flow.py # App bootstrap
├── run_postgres.sh # One-command local backend bootstrap
├── scripts/ # Shell scripts voor local setup & database
├── tests/ # Pytest & E2E integratietests
├── data/ # Externe dataset mappings
├── lucid_backend/
│ ├── main.py # FastAPI routes
│ ├── policy.py # Trigger/policy enforcement + reason codes
│ ├── models.py # SQLAlchemy modellen
│ ├── services.py # Domeinservices + seed data
│ ├── security.py # JWT decode/validate + dev token minting
│ ├── audit.py # Manifest/decision/audit registratie
│ └── schemas.py # Request/response modellen
├── alembic/
│ ├── env.py
│ └── versions/ # DB migraties
├── lucid_engineer_flow.py # App bootstrap
npm install
npm run devFrontend draait op:
http://127.0.0.1:9002
Belangrijke pagina's:
/diagnose/my-diagnoses/chat
npm run build
npm run typecheckLet op:
npm run typecheckverwacht een geldige.next/typesoutput. Draai hem dus bij voorkeur nanpm run build.- De diagnose-health is opvraagbaar via
/api/efl-core/health.
./scripts/run_postgres.shDit script doet automatisch:
- Start of herstart Docker container
lucid-postgres. - Wacht op PostgreSQL readiness.
- Zet/actualiseert
.env.lucidmet juisteDATABASE_URL. - Installeert Python dependencies in
.venv. - Draait
alembic upgrade head. - Laadt seeddata.
- Start API op
http://127.0.0.1:8010.
Handige flags:
./scripts/run_postgres.sh --with-tests # draait ook de werkbon + facturatie flow tests
./scripts/run_postgres.sh --no-api # alleen setup/migratie/seedhttp://127.0.0.1:8010/docs
De actieve Next.js EFL-routes vereisen een Firebase ID-token. De browser voegt dit token automatisch toe voor ingelogde gebruikers.
Voor server-side tokenvalidatie gebruikt de app Application Default Credentials of FIREBASE_SERVICE_ACCOUNT_JSON.
In staging en productie moet FIREBASE_SERVICE_ACCOUNT_JSON via de secret manager van de deployment worden ingesteld. Gebruik per omgeving een afzonderlijk Firebase-service-account; zet geen credentials in .env-bestanden of repositorybestanden. Voor de legacy FastAPI-JWT-laag moet LUCID_JWT_PUBLIC_KEYS_JSON verplicht worden ingesteld. De private sleutelvariabele LUCID_JWT_PRIVATE_KEYS_JSON is uitsluitend toegestaan wanneer LUCID_ENABLE_DEV_AUTH=true; zonder die dev-flag worden de ingebouwde demo-sleutels niet geladen.
Voor lokale ontwikkeling met een service-accountbestand:
export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/firebase-service-account.jsonOf configureer een JSON-string in de serveromgeving:
FIREBASE_SERVICE_ACCOUNT_JSON='{"projectId":"...","clientEmail":"...","privateKey":"..."}'Deploymentminimum voor staging/productie:
LUCID_ENABLE_DEV_AUTH=false
LUCID_JWT_PUBLIC_KEYS_JSON='{"production-key-1":"-----BEGIN PUBLIC KEY-----\\n...\\n-----END PUBLIC KEY-----"}'LUCID_JWT_PRIVATE_KEYS_JSON hoort niet in staging/productie. Ontbrekende production keys veroorzaken bewust 401 in plaats van een demo-authenticatiepad.
Garage-isolatie wordt server-side bepaald via users.firebase_uid en een actieve garage_memberships-record. Een Firebase uid, garage_id of party_id uit de requestbody of een ontbrekende membership wordt nooit als tijdelijke garage-scope gebruikt. De backend weigert toegang met 403 wanneer geen actieve membership bestaat.
Wanneer LUCID_BACKEND_URL is ingesteld, worden nieuwe cases en diagnose-uitkomsten via de beveiligde FastAPI-backend in PostgreSQL opgeslagen. Configureer daarnaast een geldig backend-JWT in LUCID_SERVICE_TOKEN en voer de migraties uit:
python -m alembic upgrade headAls LUCID_BACKEND_URL niet is ingesteld, blijft de lokale opslag uitsluitend beschikbaar voor development. Zodra de backend in een omgeving is geconfigureerd maar niet bereikbaar is, faalt de diagnoseflow expliciet en wordt niet teruggevallen op lokale opslag.
Productie start niet automatisch een schema en seedt geen demo-data. Draai migraties vooraf met Alembic. LUCID_AUTO_CREATE_SCHEMA=true is uitsluitend bedoeld voor lokale development. De Next.js Map/JSONL-opslag is alleen beschikbaar buiten productie; zet EFL_LOCAL_STORE_ENABLED=false om ook lokale development expliciet fail-closed te laten werken.
De PostgreSQL 16-migratiegate draait met:
PHASE2_POSTGRES_URL='postgresql+psycopg://user:password@host:5432/db' .venv/bin/python -m pytest -q tests/test_phase2_postgres.pyGebruik voor de volledige lokale stack:
cp env.local.example .env.local
# Vul FIREBASE_SERVICE_ACCOUNT_JSON in .env.local in.
./scripts/run_local.shrun_local.sh start Docker/PostgreSQL, voert de migraties uit, seedt de database, genereert een development-service-token, start FastAPI op poort 8010 en start daarna Next.js op poort 9002.
Een Firebase Admin service-account maak je aan in Firebase Console via Project settings → Service accounts → Generate new private key. Gebruik de JSON-waarden in .env.local; commit dit bestand nooit.
Gebruik dit als je ook de oudere/aanvullende FastAPI-backend lokaal wilt draaien.
docker run -d \
--name lucid-postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=lucid_engineer_flow \
-p 5432:5432 \
postgres:16python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements-lucid.txtMaak .env.lucid met minimaal:
DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/lucid_engineer_flow
LUCID_ENABLE_DEV_AUTH=true
LUCID_JWT_ISSUER=lucid-internal-issuer
LUCID_JWT_AUDIENCE=lucid-engineer-flow
LUCID_HMAC_SECRET=lucid-dev-hmac-secretLaad env:
set -a
source .env.lucid
set +apython -m alembic upgrade head
python -m uvicorn lucid_engineer_flow:app --reload --port 8010Belangrijkste variabelen:
| Variabele | Doel | Default |
|---|---|---|
DATABASE_URL |
SQLAlchemy connectiestring | postgresql+psycopg://postgres:postgres@localhost:5432/lucid_engineer_flow |
LUCID_ENABLE_DEV_AUTH |
Dev token endpoint aan/uit | false |
LUCID_JWT_ISSUER |
JWT issuer-validatie | lucid-internal-issuer |
LUCID_JWT_AUDIENCE |
JWT audience-validatie | lucid-engineer-flow |
LUCID_DEFAULT_JWT_KID |
default key id voor dev minting | dev-key-1 |
LUCID_JWT_PUBLIC_KEYS_JSON |
publieke keys (kid -> PEM) | ingebouwde demo key |
LUCID_JWT_PRIVATE_KEYS_JSON |
private keys voor dev minting | ingebouwde demo key |
LUCID_HMAC_SECRET |
HMAC voor anon refs | lucid-dev-hmac-secret |
LUCID_RATE_LIMIT_WINDOW |
rate-limit window sec | 60 |
LUCID_RATE_LIMIT_PER_WINDOW |
max requests per window | 60 |
LUCID_TRIGGER1_WINDOW_HOURS |
batch venster trigger 1 | 24 |
LUCID_TRIGGER1_BATCH_INTERVAL_MINUTES |
batch interval info | 60 |
party_type waarden:
garagefabrikantverzekeraar
Aanbevolen scopes:
- garage:
diagnosis:read_local,consent:write - fabrikant:
patterns:read_anon,definitions:write - verzekeraar:
claim:read_history
JWT claims die verplicht zijn:
subparty_typeparty_idscopesexp- plus header
kid
| Method | Endpoint | Doel |
|---|---|---|
GET |
/ |
protocol info |
GET |
/health |
app + DB health |
GET |
/policy/version |
policy/app versie |
POST |
/auth/dev-token |
dev JWT minten (alleen als enabled) |
POST |
/garage/diagnosis-events |
diagnose events registreren |
POST |
/claims |
claim openen |
POST |
/claims/{claim_id}/close |
claim sluiten |
POST |
/consents |
consent geven/intrekken |
POST |
/data/opvragen |
manifest-gedreven dataflow |
POST |
/fabrikant/update |
trigger 3 update push |
POST |
/jobs/trigger1/run |
trigger 1 batch run |
GET |
/manifest/audit/{manifest_id} |
echte auditrecord opvragen |
curl -X POST http://127.0.0.1:8010/auth/dev-token \
-H "Content-Type: application/json" \
-d '{
"party_type": "garage",
"party_id": "garage-001",
"scopes": ["diagnosis:read_local", "consent:write"],
"subject": "local-dev",
"expires_in_minutes": 60
}'curl -X POST http://127.0.0.1:8010/data/opvragen \
-H "Authorization: Bearer <JWT>" \
-H "Content-Type: application/json" \
-d '{
"purpose": "diagnose check",
"voertuig_id": "VTG-001"
}'- Open claim:
POST /claims - Lees claimdata 1x:
POST /data/opvragenmetclaim_id - Sluit claim:
POST /claims/{claim_id}/close - Tweede read met zelfde claim =>
403 CLAIM_ALREADY_CONSUMED
curl -X POST http://127.0.0.1:8010/jobs/trigger1/run \
-H "Authorization: Bearer <GARAGE_JWT>"| Trigger | Enforcement |
|---|---|
| T1 Garage -> Fabrikant | Alleen via batch endpoint; >=3 DTC binnen policy window; blok bij manufacturer_sharing_opt_out; output geanonimiseerd (veh_*) |
| T2 Garage -> Verzekeraar | Vereist actieve claim + consent claim_history_share + unconsumed access grant; exactly-once (CLAIM_ALREADY_CONSUMED) |
| T3 Fabrikant -> Garage | Alleen technische definitie; blokkeert contains_commercial_data=true; distributie alleen naar garages met garage_seen_codes |
Sovereignty Rule:
- Geen plain
vehicle_idbuiten garage-context. - Verzekeraar krijgt
claim_scoped_vehicle_ref.
Belangrijkste tabellen:
partiesvehiclesdiagnosis_eventsowner_consentsclaimsclaim_access_grantsmanufacturer_definitionsgarage_seen_codesmanifest_requestspolicy_decisionsaudit_eventsbatch_jobsmanufacturer_batch_records
npm run build
npm run typecheck
npm run test:efl_coreDit valideert:
- de actieve Next.js app
- de deterministische diagnose-engine in
src/efl_core - de DDS/audit response-shapes
- de procedurekern (geschiedenis/degradatie, CAN-evidence, boundary checks, SCR/NOx-gate) via
npm run test:efl_core
Let op: draai typecheck bij voorkeur na build, omdat tsconfig.json .next/types/**/*.ts meeneemt.
pytestDraait de volledige suite inclusief de werkbon + facturatie flow, autorisatie-trust-grens
en privacy-redactie tests tegen een geïsoleerde SQLite database. De PostgreSQL
migratie-gate (tests/test_phase2_postgres.py) wordt overgeslagen zonder
PHASE2_POSTGRES_URL.
Gedekte scenario's omvatten o.a.:
- auth claim-validatie
- scope violations
- trigger 2 one-time claim access
- trigger 3 commercial data blokkade
- trigger 1 anonimisering
- audit trail consistency
Dat gebeurt als typecheck draait zonder actuele .next output of parallel met een build.
Gebruik:
npm run build
npm run typecheckDit is op dit moment een bekende waarschuwing uit de bestaande Firebase-initialisatie. De build slaagt nog wel.
Gebruik altijd een virtualenv:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-lucid.txtJe zit niet in de venv, of alembic is niet geïnstalleerd.
source .venv/bin/activate
python -m alembic upgrade headPostgres draait niet:
docker ps -a
docker start lucid-postgresZet:
LUCID_ENABLE_DEV_AUTH=trueen herstart de API.
Andere server draait al op die poort. Gebruik een andere poort of stop het bestaande proces.
- De actieve diagnoseflow gebruikt geen AI-ranking meer.
- Auditregels worden lokaal append-only opgeslagen in
.efl_store/diagnosis_audit.jsonl. - Elke auditregel bevat nu een
previous_record_hashenrecord_hash. - Bij ambigue invoer geeft de engine
clarification_requiredterug in plaats van een geforceerde root cause. - Bij onvoldoende dekking geeft de engine
knowledge_gapterug. - Vervang demo JWT keys door echte key management + rotatie.
- Zet
LUCID_ENABLE_DEV_AUTH=falsebuiten development. - Gebruik sterke
LUCID_HMAC_SECRET. - Zet DB backups, connection pooling en monitoring aan.
- Overweeg immutable audit storage voor compliance.
Voor lokaal snel starten: ./run_postgres.sh --with-tests --no-api geeft je een complete setup + validatie in één run.

