bin/docs/superpowers/specs/2026-07-09-langflow-projekt-matching-design.md

Design: Automated project–skill matching in Langflow with CRM entry

Date: 2026-07-09 Status: approved section by section in brainstorming; pending final spec review

1. Goal

Convert the interactive Claude skill projekt-anlegen (/home/tlg/mkt/bewerb/.claude/skills/projekt-anlegen/SKILL.md) into a fully automated Langflow workflow:

• Triggered by new e-mails with freelance project descriptions arriving at chancen@destengs.com.
• Uses ONLY the local AI at the vLLM OpenAI-compatible endpoint http://127.0.0.1:8081/v1 (model AxionML/Qwen3.5-9B-NVFP4).
• No human review pause (the skill's Schritt 6 is removed; ambiguities are resolved by defaults, see §5.2).
• Projects with Must-have-Match > 85 % are written to EspoCRM (full replication: Account, Contact, Opportunity) and announced by notification e-mail; all others are rejected silently (trace only).
• Every run is traced in Langfuse for manual quality annotation.

Infrastructure (existing)

Service	Address	Notes
Langflow	http://127.0.0.1:8090	rootless podman pod langflow_pod
Langfuse	http://127.0.0.1:8091	pod-internal: http://langflow_pod:3000
vLLM	http://127.0.0.1:8081/v1	from pod: http://host.containers.internal:8081/v1; reasoning model, 65k context
EspoCRM	https://crm.creature-go.com	API creds in /home/tlg/mkt/bewerb/.secrets/espocrm-api.md
Mail	mail.destengs.com	IMAP 993/SSL, SMTP 587/STARTTLS, account chancen@destengs.com

Reference inputs (read-only): vorgaben/Lebenslauf_Dr-Ing_Thomas_Langer.md, vorgaben/rahmenbedingungen.md under /home/tlg/mkt/bewerb/.

2. Decisions made during brainstorming

Topic	Decision
CRM scope	Full replication of the skill: Account (dedup/create, Reseller/Customer) + Contact (dedup/create) + Opportunity (team, agency/direct linking)
Duplicate key	Canonical project URL (redirect followed, query stripped), stored in and matched against cProjektlink
Langfuse evaluation	Tracing + manual annotation (score configs + annotation queue); no LLM-as-judge
Mailbox	Only ONE address exists: chancen@destengs.com ("chances@" in the original brief was a typo). Design-phase notifications go there; production notifications to Thomas.Langer@destengs.com
Trigger cadence	Poll every 5 minutes
Non-project mail	Left untouched in the Inbox, marked with an IMAP keyword so it is inspected only once
Retry policy	No cross-cycle retries for processing errors: every project reaches a terminal state on first attempt; trigger mail is then ALWAYS moved to Trash; failures produce an aggregated alert mail. Only Flow-1-level failures (IMAP down, lock held) wait for the next cycle
Architecture	A: two Langflow flows (Ingest + Per-Project) + systemd timer webhook trigger
Fetch failure	No snippet fallback: alert mail + terminal state failed, nothing written to CRM
max_tokens	Effectively unbounded (no ~4k cap); reasoning model may need long chains
Notification subject	[Projekt-Match] Freelancermap — <Must> % — <Name>
Alert subject	[Projekt-Match-Fehler] Freelancermap — <n> Projekt(e)

3. Architecture overview

systemd user timer (5 min)
      │ curl POST /api/v1/webhook/<flow1_id>   (returns immediately)
      ▼
┌─ Flow 1: INGEST ───────────────────────────────┐
│ lockfile guard (skip run if another is active) │
│ IMAP poll: INBOX without keyword $ProjektChecked│
│ → project-mail detection (deterministic)       │
│ → split mail into project items                │
│ → canonical URL per item (follow redirects)    │
│ → CRM dedup: Opportunity.cProjektlink equals   │
│ → for each NEW project: run Flow 2 via API ────┼──┐
│ → aggregate results                            │  │
│ → failures? ONE alert mail per trigger mail    │  │
│ → all terminal? move trigger mail → Trash      │  │
│ → non-project mail: flag $ProjektChecked, keep │  │
└────────────────────────────────────────────────┘  │
┌─ Flow 2: PER-PROJECT ──────────────────────────┐ ◀┘
│ fetch page text → LLM extract → LLM CV-match   │
│ → deterministic Misc rules + match calculation │
│ → gate Must-have-Match > 85 %                  │
│ → yes: CRM writes + notification mail          │
│ → no: end (trace only)                         │
│ returns {status, error?, opportunityId?, …}    │
└────────────────────────────────────────────────┘

Control flow (loops, conditionals) lives in custom Python components inside the flows; the systemd timer carries no logic. One Flow 2 run per project ⇒ one Langfuse trace per project.

4. Flow 1: Ingest

1. Lock. Acquire a lockfile in the Langflow data dir. If held: exit immediately (a previous run is still working; state lives in the inbox, so nothing is lost — worst case a mail starts ~10 min after arrival instead of 5).
2. IMAP poll. mail.destengs.com:993 SSL, login chancen@destengs.com. Select INBOX; fetch messages NOT carrying custom IMAP keyword $ProjektChecked.
3. Project-mail detection — deterministic, no LLM:
   • Own workflow mails (subject starts [Projekt-Match] or [Projekt-Match-Fehler]) → skip, flag $ProjektChecked.
   • Mail contains freelancermap project URLs (/nproj/… or /projekt/…) → project mail.
   • Anything else → flag $ProjektChecked, leave untouched in Inbox.
4. Split. Parse body (HTML preferred, else plain text); extract each project item: title + tracking URL. (Example 1 yields 5 items.)
5. Canonical URL. GET each tracking URL following redirects; strip query string → e.g. https://www.freelancermap.de/projekt/python-entwickler-fuer-eine-ki-anwendung-m-w-d. Resolution failure → item is terminal failed with reason.
6. CRM dedup. GET /Opportunity where cProjektlink equals <canonical>; hit → terminal duplicate.
7. Dispatch. For each remaining project: POST /api/v1/run/<flow2_id> (header x-api-key) with canonical URL and title. Await result: created / rejected / failed (+ error reason, opportunity ID, match values).
8. Alerting. If ≥ 1 project ended failed: send ONE alert mail per trigger mail — subject [Projekt-Match-Fehler] Freelancermap — <n> Projekt(e), body listing each failed project (title, URL, error reason). All alerting lives here; Flow 2 only returns status.
9. Finalize. All items terminal (created/rejected/duplicate/ failed) — which is always true at this point — → move trigger mail to Trash (IMAP MOVE, fallback COPY+\Deleted+EXPUNGE). Release lock.

5. Flow 2: Per-Project

Input: canonical URL, title. Output: {status, error?, opportunityId?, mustMatch?, niceMatch?, projectName?}.

5.1 Fetch

GET canonical URL, extract readable text. 2–3 in-run retries with short backoff for transient HTTP errors. Still failing (or login wall / empty text) → return failed with reason; NO fallback to e-mail snippet text (a snippet cannot support a reasonable requirements matching).

5.2 LLM call 1 — Extraction

vLLM chat completion, guided_json schema enforcement, no restrictive max_tokens (leave unset / remaining-context; reasoning chains may be long). Output JSON:

• projectName (without portal suffix),
• requirements[]: verbatim text (careful shortening allowed, meaning never changed) + category Must/Nice/Misc — explicit section headings outrank signal words; Rahmenbedingungen (start, location/remote, workload, duration) are Misc,
• offerType: Projekt / Arbeitnehmer-Angebot / ANÜ (→ team DesTEngS / Arbeitnehmer / ANÜ),
• buyerType: agency / direct,
• companyName, contactPerson (nullable).

Prompt includes few-shot examples. Defaults replace the skill's "ask in review": ambiguous offerType → Projekt; ambiguous buyerType → agency. Schema-invalid output after retry → failed.

5.3 LLM call 2 — CV matching

One call: full CV markdown + all Must/Nice requirements → per requirement ✅/❌/❔ + one-line justification. Prompt carries the skill's strict calibration (✅ only on clear CV evidence; PoC ≠ production operation; "mehrjährig" taken literally; product name ≠ platform experience; "wie z. B."-lists: equivalent alternatives count; ❔ only for genuine partial evidence). Misc items are NOT sent to the LLM.

5.4 Deterministic rules (pure Python — numbers never come from the LLM)

• Misc evaluation (from rahmenbedingungen.md, same rules as skill Schritt 3b): Start ≤ today + 56 days → ✅ else ❌, missing → ❔; workload 75–100 % → ✅, < 75 % or missing → ❔; duration always ✅; 100 % remote → ✅, hybrid/onsite → Nominatim geocode + Haversine distance to Sauerlach (47.9721 N, 11.6528 E): ≤ 50 km ✅, 50–60 km ❔, > 60 km ❌, unclear → ❌, geocode failure → ❔ (NOT a run failure); Sicherheitsüberprüfung demanded → always ❌.
• Match computation: mean over Must rows with ✅=100, ❔=25, ❌=0; same for Nice; Misc never enters a match; round to whole percent; empty category → –.
• Description markdown in the skill's exact Schritt-5 format: match line (Must-have-Match: X % · Nice-to-have-Match: Y %), table | Nr. | Kat. | ❔ | Anforderung |, order Must → Nice → Misc, numbering from 1.

5.5 Gate

Must-have-Match > 85 → CRM branch. Otherwise: terminal rejected — no CRM write, no mail; matches/table/decision recorded in the Langfuse trace.

5.6 CRM writes (EspoCRM API, skill Schritt 7 replicated)

1. Team-ID by name lookup (from offerType); never guessed; lookup empty → failed.
2. Account dedup (contains on a core name token) else create (type: Reseller for agency, Customer for direct).
3. Contact dedup (last name) else create with accountId (last token = lastName, rest = firstName). No contact person named → Opportunity created WITHOUT contact (automation simplification).
4. Opportunity name-duplicate check (startsWith), suffix (2), (3)…; create with description markdown, cProjektlink = canonical URL, teamsIds, and agency → cAccount1Id (no accountId) / direct → accountId (no cAccount1Id).
5. Verify read-back: name, link, description intact (match line + all rows), linking correct, team correct. Mismatch → failed.

CRM errors get 2–3 in-run retries (transient); persistent error → failed. Partial writes heal on a later attempt because Account/Contact/Opportunity creation are each dedup-guarded.

5.7 Notification mail

SMTP mail.destengs.com:587 STARTTLS. Subject: [Projekt-Match] Freelancermap — <Must> % — <Name>. Body: short note, both match values, direct link https://crm.creature-go.com/#Opportunity/view/<id>. Recipient from config variable: design phase chancen@destengs.com, after gates 1+2 pass Thomas.Langer@destengs.com.

6. Langfuse monitoring

• Integration: Langflow-native via env vars on the Langflow container: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST=http://langflow_pod:3000 (pod-internal address — langfuse-web binds the pod IP, not localhost). Dedicated Langfuse project projekt-matching.
• Trace content: automatic spans for all components incl. both LLM calls (prompts + outputs); Flow 2 additionally attaches metadata via the Langfuse SDK: canonical URL, requirement table, both match values, decision, CRM opportunity ID. Traces are filterable by decision.
• Manual annotation (chosen eval mode): two score configs — extraction-correct (Must/Nice/Misc correctly derived?) and matching-correct (✅/❌/❔ against CV correct?) — plus one annotation queue fed by Flow 2 traces. Thomas scores in the Langfuse UI (:8091); scores are a quality record only, no automation acts on them.

7. Configuration and secrets

• All runtime settings in Langflow global variables (encrypted in Langflow's Postgres): IMAP/SMTP credentials, EspoCRM base URL + API key, notification recipient, alert recipient, match threshold (85), vLLM endpoint + model name. The EspoCRM key is read from /home/tlg/mkt/bewerb/.secrets/espocrm-api.md once during setup; it never appears in flow JSON, git, or chat.
• CV and rahmenbedingungen.md are copied into the bind-mounted Langflow data dir; components read them at runtime. CV update = file replacement, no flow edit.
• Both flows are exported as JSON into a git-tracked project directory (restorable); custom component code lives there too.

8. Error handling

Principle: terminal state on first attempt, alert instead of retry loops. In-run robustness (2–3 short HTTP retries against freelancermap, vLLM, CRM, Nominatim) absorbs transient hiccups; nothing is retried across cycles.

Failure	Behavior
Langflow down at timer tick	curl fails silently; next tick retries; inbox holds state
Flow 1: IMAP unreachable / lock held	Run aborts/skips; mails untouched; next cycle retries; no alert
URL resolution / page fetch fails	Project terminal failed; listed in aggregated alert
vLLM error / schema-invalid JSON	Project terminal failed; alert
CRM error (persistent)	Project terminal failed; alert
Nominatim failure	That Misc row → ❔; run continues (skill rule)
Opportunity created, notification send fails	Accepted edge case: retryless design means no resend; trace records it
Match-value drift over time	Start-date rule is date-relative; gates test thresholds, not exact values

Trigger mail ALWAYS reaches Trash once every contained project is terminal (created/rejected/duplicate/failed) — errors surface via the alert mail and failed Langfuse traces, never via inbox accumulation.

9. Test plan

Known references from the skill: example 1 project 4 (…/projekt/python-entwickler-fuer-eine-ki-anwendung-m-w-d) scored 86 % Must; example 2 (…/projekt/test-engineer-m-w-d-3020995) scored 25 % Must. Before every CRM-writing test, opportunities whose cProjektlink matches the canonical test URLs are deleted — including those the original Claude skill created — else dedup blocks the test.

1. Component tests: invoke Flow 2 directly via the run API for both example projects. Verify exact description format, threshold behavior (> 85 % / < 50 %), CRM entities and linking, verify read-back.
2. Gate 1 (consider): self-built projektagent-style mail with example 1's five projects sent chancen@ → chancen@. Expect: five Flow 2 runs, project 4 in CRM (Must > 85 %, the skill scored it 86 %), notification [Projekt-Match] Freelancermap — <Must> % — … at chancen@, trigger mail in Trash, five Langfuse traces.
3. Gate 2 (reject): example-2 mail. Expect: trace with table and matches, Must < 50 %, no CRM entry, no notification, mail in Trash.
4. Dedup test: resend gate-1 mail. Expect: no second opportunity, no second notification, mail in Trash.
5. Recipient flip: notification AND alert recipient variables → Thomas.Langer@destengs.com. Design phase ends.
6. Gate 3: delete test opportunity, resend example-1 mail. Expect: CRM entry re-created, notification to Thomas.Langer@destengs.com; receipt confirmed by Thomas (that inbox is not accessible to the automation builder).

10. Out of scope

• Portals other than freelancermap (detection is URL-based; other portals are an extension point in Flow 1 step 3/4).
• Login-protected ausschreibungen (fetch fails → alert; no snippet fallback).
• LLM-as-judge evaluation, automated actions on Langfuse scores.
• Resending notifications lost to the accepted SMTP edge case (§8).