Glossary

Glossary

Reference — domain vocabulary. Terms that recur across code, docs, and specs.

Users

Consumer — End user looking for skilled trade services. Two modes:

• Planned consumer: browses calmly, evening/weekend, compares pros. ~80% of flows.
• Emergency consumer: SOS mode — broken lock, flood, no heat. Needs immediate dispatch. ~20%.

Professional (a.k.a. pro) — Italian tradesperson (plumber, electrician, HVAC, locksmith, carpenter, painter) accepting bookings on Ideony. 30–60yo target demographic. May have older phones, limited English.

Admin — Ideony staff reviewing credential submissions, moderating reviews, handling disputes.

Discovery & booking

Category — Canonical trade slug. Current set: plumbing, electrical, hvac, locksmith, carpentry, painting (+ child categories). Slug vocabulary is locked across FE, BE, AI prompts.

Triage — Conversational follow-up between prompt submission and results. 4–6 structured questions (urgency, home age, photo) refine the match. Implemented via LangGraph agent w/ tool-use.

Candidate — A professional selected by the matching engine for a given request. SOS dispatch pushes to top N candidates in radius tiers.

Booking — Normal-mode request: consumer → pro, scheduled. Lifecycle: PENDING → ACCEPTED → IN_PROGRESS → COMPLETED → CONFIRMED (escrow released at this step; auto-release 48h if no consumer action).

Dispute — Consumer-raised freeze on a booking’s escrow. Triggers platform mediation.

Change order — Pro-requested price adjustment mid-job. Consumer approves or rejects.

SOS

SOS dispatch — Emergency-mode flow. Consumer taps SOS button → API finds pros in radius tiers → pushes to top N simultaneously → first accept atomically locks dispatch (others get “taken”).

Radius tier — Successive PostGIS geo-queries at 1 km → 3 km → 5 km → 10 km until enough candidates found.

Live tracking (Tier 2) — Locked 2026-04-19. Polyline drawn once on pro-accept via Mapbox Directions; redrawn only on >200m deviation. ~3 Mapbox API calls per dispatch. Pro nav handoff = OS deep-link chooser (Apple Maps / Google Maps / Waze), not in-app turn-by-turn.

Trust & credentials

Credential — Pro-uploaded document. 8 types: P_IVA (VAT number, optional <€5k/yr — prestazione occasionale), INSURANCE, ALBO (professional register), F_GAS (refrigerant certification), ID_DOCUMENT, TRAINING_DIPLOMA, MANUFACTURER_CERT, OTHER.

Trust score — Integer score. Weights: P_IVA=30, INSURANCE=25, ALBO=20, F_GAS=15, TRAINING_DIPLOMA=10, MANUFACTURER_CERT=10, ID_DOCUMENT=10, OTHER=5.

Trust tier — Derived label from trust score:

• BASIC — 0–30
• VERIFIED — 31–70
• ELITE — 71+

Verificato badge — UI badge tied to trust tier. Three visual states: Verified (green check), Pending (“Verifica in corso”), Unverified (no badge, lower ranking).

Pricing

Two pricing modes (locked product decision):

• Fixed — “€50 fisso” — commodity categories, published single price
• Hourly — “€45/h” — bespoke jobs, hourly rate

Card UI must visually distinguish the two modes.

Consumer fee — Platform fee added on top of pro price, 8–10%.

Distance fee — €0.50/km for travel.

Escrow — Stripe-held funds. Released to pro on consumer confirmation or 48h auto-release.

AI & agentic

Prompt-first home — Main consumer screen. Large textarea with placeholder “Descrivi il tuo problema…”, photo/video attachment. Not a category grid.

Job parser — LangGraph StateGraph agent that converts freeform problem text → structured {category, urgency, details}. Falls back to Gemini 2.5 Flash when OpenAI primary fails.

Smart search — AI-powered natural-language → category matching + inline AI banner on results.

Infrastructure

MVP 0 — First testable release with cofounders. Current milestone. Targets ~€5/mo infra cost on Hetzner CAX11.

Quick Tunnel — Cloudflare’s ephemeral tunnel (*.trycloudflare.com). Interim prod exposure. URLs rotate on cloudflared restart.

Named tunnel — Persistent Cloudflare tunnel at ideony.is-a.dev. Blocked on is-a-dev PR #36614 merge.

Blue-green swap — Dokploy deploy pattern: new image pulled, health-checked, traffic swapped, old container kept briefly for rollback.

Testing

BAPI session auth — Clerk Backend API endpoint used in E2E tests to mint session tokens. Bypasses FAPI rate limits (429s).

Multi-role E2E — Dual-actor test scenarios (consumer + pro acting concurrently). Covers booking handoff, chat, SOS accept race. Spec lives at ./specs/2026-04-20-phase-e-multi-role-e2e-spec.md.

i18n

Italian-first — Copy written in Italian first, English second. Translation keys in BE (nestjs-i18n) + FE (i18next + expo-localization).

Regional specificity — “Milano, Zona 9” beats generic “near you”.

Related

Links: ./architecture.md, ./design-system.md, ./specs/.