# KLIGO phased integration checklist

This sequence converts the current prototype into a working pilot while protecting the already-approved UI. A phase is complete only when its exit gate passes; visual presence is not evidence of backend completion.

Use `HANDOFF_READINESS.md` to distinguish kickoff decisions from later launch gates. The current route tree is generated in `CURRENT_ROUTE_INVENTORY.md`.

Confirmed scope: see `LAUNCH_SCOPE.md`. Website first; all four categories; subscriptions and paid placements only. Deals and deal payments stay between buyer and provider.

## Phase 0 - Kickoff decisions and later launch requirements

- [ ] Confirm pilot audience: ChatGPT/Sites-authenticated invitees or general public accounts.
- [ ] Preserve implemented `/sign-in`; add `/login` only as a compatibility redirect if needed.
- [ ] Approve customer/provider/staff role matrix and provider-team ownership model.
- [ ] Approve legal entity, Terms, Privacy Policy, cookie/analytics position and versioned consent fields.
- [x] Viktor confirmed direct provider deals; no KLIGO deal checkout, commission, escrow or seller payouts.
- [ ] Select payment provider only after merchant-country, ILS, subscription/placement billing, refund and Israeli invoicing checks.
- [ ] Choose production maps/geocoding and approve address privacy/retention rules. Current rendering uses MapLibre/OpenFreeMap; Google is an unapproved alternative.
- [ ] Confirm support/moderation owners, response targets, evidence retention and emergency escalation wording.
- [ ] Supply or approve clearly labelled sample inventory until verified providers onboard.

**Kickoff gate:** agree first-release scope, commercial workflow, account roles, technical ownership and the first implementation milestone. Do not delay initial sample-data development for later vendor or legal decisions. Resolve each vendor before its integration and approve legal/retention rules before real collection or transactions. Record the decisions and their owners.

## Phase 1 - Persistence and authorization foundation

- [ ] Confirm the proposed Cloudflare/D1/R2 stack or document the selected equivalent. If using Sites D1, bind it as `DB`; add R2 when the upload slice begins.
- [ ] Implement Drizzle schemas for users, roles, provider organizations/memberships and audit events first.
- [ ] Generate and inspect append-only migrations; add foreign keys and only query-driven indexes.
- [ ] Implement `currentActor`, `requireUser`, `requireRole`, `requireProviderMembership` and resource-ownership checks.
- [ ] Protect all `/customer/*`, `/provider/*` and future `/admin/*` routes server-side.
- [ ] Separate moderator/admin routes from the provider namespace.
- [ ] Add structured server logging, request correlation IDs, mutation idempotency and safe error responses.
- [ ] Establish local/staging seed data that is unmistakably non-production and excluded from real analytics.

**Exit gate:** anonymous users cannot read or mutate account data; customers cannot access other customers; provider members cannot cross organizations; staff actions are auditable.

## Phase 2 - Real account lifecycle

- [ ] Implement the approved identity provider end-to-end; remove simulated password/OTP acceptance.
- [ ] Create/link a D1 user record only after verified identity.
- [ ] Persist role choice, service area, category interests, locale and consent versions.
- [ ] Implement provider organization creation and invitation/membership acceptance.
- [ ] Add rate limiting, anti-enumeration, session invalidation and provider-owned recovery.
- [ ] Redirect successful onboarding to `/customer` or `/provider`, not the homepage.
- [ ] Add account suspension/deletion/export operational paths before public launch.

**Exit gate:** sign-up, sign-in, sign-out, recovery, onboarding and role-aware redirects work with real identities and server authorization.

## Phase 3 - Marketplace source of truth

- [ ] Implement categories/taxonomy as managed data with stable slugs.
- [ ] Implement new/surplus material source, remaining quantity/unit, condition, collection terms and sold-out handling; follow `MATERIALS_HANDOFF.md`.
- [ ] Implement listing core plus equipment/service/part/material subtype tables. Projects is retired and outside launch scope unless separately reapproved.
- [ ] Replace `catalog-data.ts` arrays through a repository/adapter without rewriting route UI.
- [ ] Implement draft, review, publish, pause and archive transitions with audit events.
- [ ] Return only `published` records publicly; retain sample badge logic for explicitly seeded content.
- [ ] Add D1 filters for type, category, status, area, price mode and availability; keep query state in the URL.
- [ ] Preserve canonical `/providers/[slug]` profiles and service compatibility routes; never use a private workspace preview as a public destination.
- [ ] Prevent duplicate slugs and define redirect/history behavior after slug changes.

**Exit gate:** one verified provider can create a draft listing, submit it, receive approval and see it publicly without manual database edits.

## Phase 4 - Uploads and verification

- [ ] Bind R2 and define separate public-listing and private-evidence key spaces/access policies.
- [ ] Implement short-lived signed upload flow with server-issued object keys.
- [ ] Enforce file count, size, declared/actual MIME type, image dimensions and checksums.
- [ ] Quarantine until malware/content checks finish; create optimized image derivatives.
- [ ] Persist rights/source metadata for marketplace photography.
- [ ] Implement verification cases/documents/checks, expiry and revocation.
- [ ] Ensure raw identity/insurance documents are never served through public URLs.
- [ ] Add deletion/retention jobs and orphan-object cleanup.

**Exit gate:** a provider can upload listing media and private verification evidence; public users see only approved derivatives; unauthorized object access fails.

## Phase 5 - Requests and matching

- [ ] Persist multi-step customer drafts server-side without losing user input on transient failure.
- [ ] Upload request attachments through the private R2 path.
- [ ] Submit requests transactionally with items, location, schedule and event record.
- [ ] Match only eligible providers by category, service area, listing status, verification and availability policy.
- [ ] Record match reason codes and allow staff to diagnose why a provider was or was not matched.
- [ ] Notify providers without leaking exact private site information prematurely.
- [ ] Add request detail route and lifecycle actions missing from the current list UI.

**Exit gate:** a real customer request reaches only eligible provider accounts and remains traceable from submission through response.

## Phase 6 - Quotes and direct provider deals

- [ ] Confirm which request/quote status tracking is needed for the lead marketplace.
- [ ] Persist provider responses/quote versions and deliver notifications only to authorized parties.
- [ ] Make direct provider responsibility for availability, fulfilment and deal payment clear.
- [ ] Adapt or retire historical booking, deposit, transaction payment and payout screens/links before launch. Do not build KLIGO deal checkout, commission or guaranteed reservations.

**Exit gate:** the customer reaches the intended provider and receives a durable response; no demo status falsely confirms inventory, fulfilment or payment.

## Phase 7 - Messaging and notifications

- [ ] Create conversations tied to request, quote, booking, support or report context.
- [ ] Authorize every participant on reads, sends, attachments and read receipts.
- [ ] Persist messages and unread counters; pilot with bounded polling.
- [ ] Add email/SMS/push notification adapters with user preference and consent checks.
- [ ] Add delivery failure/retry policy and deduplicate notification events.
- [ ] Sanitize message content and define edit/delete/retention policy.
- [ ] Decide whether realtime transport is justified from measured pilot behavior.

**Exit gate:** customer/provider messages survive reload, notify the other party and cannot be read by non-participants.

## Phase 8 - Subscription and paid-placement billing

- [ ] Keep buyer/supplier deal payments outside KLIGO; remove historical checkout entry points from the production journey.
- [ ] Implement subscription and paid-placement billing as the confirmed KLIGO revenue model.
- [ ] Store only PSP customer/payment/subscription references and display-safe metadata.
- [ ] Verify webhook signatures; deduplicate by provider event ID; process asynchronously/idempotently.
- [ ] Activate paid plans and placements only from authoritative payment events; never mark an external deal paid or confirmed.
- [ ] Implement failed payment, cancellation, refund and dispute paths before accepting live money.
- [ ] Integrate compliant invoice/receipt generation and tax identity validation.
- [ ] Reconcile PSP totals to KLIGO payment records and expose an operations exception queue.

**Exit gate:** sandbox money flows reconcile end-to-end; replayed webhooks cause no duplicate entitlement or placement; finance/legal sign off before live mode.

## Phase 9 - Maps and production search

- [ ] Configure the approved tile/geocoding vendor, any required restricted keys, attribution and usage budgets/alerts.
- [ ] Implement localized place autocomplete/geocoding with Israel region bias.
- [ ] Store the selected vendor’s place reference, normalized location and coordinates; ask the user to confirm the chosen place.
- [ ] Show coarse/rounded public location and exact address only to authorized booking parties.
- [ ] Replace approximate seed-city pins with verified, privacy-safe production coordinates and preserve accessible list equivalence.
- [ ] Measure search quality in Hebrew, Arabic and English before selecting an external index.
- [ ] If needed, implement an HTTP search adapter, indexing queue, reindex command and D1 reconciliation.

**Exit gate:** map/list results are consistent, address privacy is enforced and search relevance is validated with real queries in all launch languages.

## Phase 10 - Trust, moderation and operations

- [ ] Move moderation to `/admin/moderation` with staff-only authorization.
- [ ] Implement report intake, private evidence, triage, assignment, decisions and appeals.
- [ ] Use explicit policy codes/versions and append-only moderation actions.
- [ ] Notify affected parties with redacted, role-appropriate details.
- [ ] Implement verification expiry/review reminders and emergency escalation rules.
- [ ] Add support case ownership, SLAs, internal notes and customer/provider-visible updates.
- [ ] Add dashboards for stuck requests, failed notifications, payment exceptions and storage-processing failures.
- [ ] Run tabletop exercises for account takeover, unsafe listing, payment dispute and evidence disclosure.

**Exit gate:** authorized staff can resolve a case without direct database edits and every sensitive read/write is auditable.

## Phase 11 - Launch hardening

- [ ] Replace the existing `/privacy`, `/terms` and `/cookies` drafts with approved text; link exact versions from account creation.
- [ ] Reconcile `CURRENT_ROUTE_INVENTORY.md` with launch scope and remove dead destinations; do not reintroduce retired Projects routes.
- [ ] Remove demo records from production or retain only those explicitly labelled and excluded from KPIs.
- [ ] Test critical flows for customer, provider, moderator and unauthorized user.
- [ ] Test idempotency, concurrency, retries, webhook replay, upload abuse and ownership attacks.
- [ ] Validate backups/export, migration rollback strategy and incident runbooks.
- [ ] Validate Hebrew/Arabic RTL, timezone, ILS rounding, accessibility and mobile behavior.
- [ ] Add privacy-safe monitoring, alerting and rate/cost budgets.
- [ ] Complete legal, finance, security, support and content readiness sign-off.

**Exit gate:** the production readiness review has named owners, evidence and rollback/incident paths. Publishing remains a separate, explicit release action.

## Credential and decision register

| Dependency | Needed before | Owner/input |
| --- | --- | --- |
| Sites auth or external identity configuration | Phase 2 | Product + technical owner |
| SMS/OTP billing and sender configuration | Phase 2 | Product/legal + identity vendor |
| D1 binding | Phase 1 | Sites project owner |
| R2 binding and object access policy | Phase 4 | Technical owner |
| Approved map/geocoding service, restrictions and billing | Phase 9 | Technical/billing owner |
| PSP sandbox/live keys and webhook secret | Phase 8 | Legal entity + finance + technical owner |
| Email/SMS/push provider credentials | Phase 7 | Marketing/support + technical owner |
| Admin bootstrap and staff list | Phase 1/10 | KLIGO owner |
| Terms, Privacy, cookie/analytics and retention policy | Phase 0/11 | Legal owner |
| Real provider/listing data and verification evidence | Phase 3/4 | Provider operations |

## Definition of a live feature

A feature is live only when it has persistent records, server-side authentication and authorization, validated mutations, recoverable errors, auditability, real empty/loading/error states, privacy rules, monitoring and an accountable operational owner. A clickable interface or local state change alone is still a prototype.