# KLIGO detailed implementation reference

> Scope update (12 September 2026): `LAUNCH_SCOPE.md` takes precedence. Website first; native app later; all four categories. KLIGO bills subscriptions and paid placements only. Historical buyer-deal checkout, commission, escrow, booking-payment and payout proposals below are excluded from launch. See `MATERIALS_HANDOFF.md` for new/surplus material fields.


## Start here — choose the right download

Read `docs/HANDOFF_READINESS.md` first for kickoff decisions, current interface rules and launch gates. `docs/CURRENT_ROUTE_INVENTORY.md` lists the current route tree; older architecture inventories are historical.

1. **Complete website source** is the runnable web reference. Extract it and open the `kligo-website/` folder. It includes routes, components, images, data templates, database schema, translations, tests and setup scripts.
2. **Developer kit package** is a design/component reference, not a standalone application. It includes logos, font configuration/tokens, shared components and handoff notes. Use the complete source ZIP to run the site.
3. Open `/design-system` in the running website to inspect the approved controls. Use **For developer** for contextual notes and **Clean examples** for uncluttered examples without deleting inventory.
4. Read `docs/HEBREW_LOCALIZATION.md`, `docs/ARABIC_LOCALIZATION.md` and `docs/MOBILE_APP_HANDOFF.md` before multilingual or native-app implementation. Hebrew UI is a presentation localization; it does not replace native-language, legal or accessibility review. Technical handoff documents are in English.

Both archives include this `START_HERE.md`. Downloads do not include production credentials, a payment integration or native app-store binaries. The existing photo-guide PDF is English; the translated web guide supports browser print/save-to-PDF.

## Mobile application handoff

The approved mobile grid/list revision uses `MobileListingContent` inside the shared `ListingCard`. At widths below 768px it replaces the desktop body, with two-column discovery grids (one column below 360px), white card surfaces, #FBB104 sponsorship/status accents, photos cropped to fill their rounded frames, real carousel dots and contextual bottom-sheet actions. List mode has a square image and yellow arrow. Saved mobile lists and map results share this template; the current desktop list/map refinements are described in `HANDOFF_READINESS.md`. Mobile saved results paginate in groups of eight. Shared mobile actions have a 44px minimum touch target; category filters use compact two-column rows. `HomeDiscovery` connects Browse Categories to the search scope and hides the duplicate mobile search category selector. Company cards pair an original provider logo symbol with a readable name and direct link. The header scrolls normally and closes its controlled menu on route changes. The supplied mockups guide presentation; native app development is outside this design-prototype scope.

Start with `docs/MOBILE_APP_HANDOFF.md` for the native app scope, reusable sources, route map and acceptance criteria. The Developer Kit's Mobile section links directly to working web screens and demonstrates customer/provider bottom navigation. It does not contain a second mock application. Both downloads include the guide; the website ZIP is the complete responsive web reference, not native iOS/Android source. A native app and shared production backend remain to be implemented.

## Simplified discovery and provider hub

Equipment, services, parts, materials and companies reuse `DiscoverySearch`, with no enclosing card behind the individual controls. Service/part/material pages put compact category buttons under the search alongside the filter toolbar. Advanced filters stay anchored to their trigger and have an explicit Show results action. Options are contextual: equipment operator/delivery, service provider type, parts compatibility, material quantity. Date requests remain subject to provider confirmation, not live availability guarantees.

`/providers` is the company-management and policy hub; `/legal` redirects to its policies section. Existing policy detail routes and operational destinations remain intact. No policy text was changed or approved as legal advice. Final browser-based desktop/mobile review is still pending; do not interpret automated checks as visual validation.

## Home categories and companies

`BrowseCategories` uses the existing KLIGO tabs and keeps the chosen category group on the same page. Each group has six linked cards in three desktop columns. Equipment reuses the approved images; services, parts and materials each use a compressed 3 × 2 image sheet with lazy loading. These are representative AI-generated category images, not inventory evidence.

`CompactCompanyCard` is shared by the home page, `/companies` and the trusted directory. The 19 fictional companies have distinct original SVG symbols and wordmarks in `public/companies/logos`; unknown company names use a readable text fallback. The official KLIGO logo remains unchanged. `/companies` searches actual names and services, filters business types and area, and opens the canonical profile. Requested dates must be confirmed with the company.

Company campaigns resolve by canonical profile URL, active dates and placement. Home/directory/trusted cards use the one-in-eight sponsorship cap. Homepage and category banners are separate single slots. Category sponsorship appears in matching excavator or wheel-loader searches, or the groundworks services category. Paused, draft, expired or mismatched campaigns are not delivered. Trusted placement requires the existing demo identity review; browser-local company profiles stay pending and cannot buy approval. Production needs authoritative company IDs, verified review status, slot availability, scheduling, targeting, moderation and measurement on the server.

Start with the working website and `/design-system`. The **For developer** action opens page-specific notes. **Clean examples** temporarily reduces repeated cards and replaces their pictures with empty image areas. Leaving developer view restores the complete presentation; it never removes records.

## Run and review

The source download keeps the original folders and lockfile. Use Node 22.13+, npm and Bash on Linux/WSL2. macOS requires GNU coreutils (`timeout` on PATH); native Windows without Bash is not supported by these scripts. The build script also needs GNU `timeout` (provided by coreutils on Linux). From `kligo-website/`, run `npm ci`, then `npm run dev`. `npm run build` creates the Cloudflare-compatible worker and assets; `node --test --test-concurrency=1 tests/*.test.mjs` verifies the built application. The build also refreshes both downloads with Node built-ins.

The source package deliberately excludes credentials, environment files, hosted project bindings, Git history, build output and browser data. A sanitized `.openai/hosting.json` keeps local builds working without identifying the hosted project. Configure your own deployment project and environment. It does not grant access to the existing hosted KLIGO project. Follow the package scripts rather than replacing dependencies during handoff.

## Folder map

| Folder | Responsibility |
| --- | --- |
| `app/` | Public, customer and provider routes; shared layout and CSS |
| `components/kligo/` | Approved buttons, cards, tabs, overlays and loader |
| `components/marketplace/` | Catalog, search, maps and listing details |
| `components/profiles/` | Public company identities and presentation |
| `components/provider/` | Listing creation, profile, campaigns, plans and billing |
| `components/customer/` | Requests, quotes, saved items and messages |
| `components/i18n/` | Locale context and shared English/Hebrew/Arabic labels |
| `components/developer/` | Optional review mode, isolated from customer browsing |
| `components/ui/` | Installed primitives; compose through KLIGO wrappers |
| `public/` | Official logos, optimized catalog pictures and image licenses |
| `tests/` | Workflow, route and data-contract checks |

## Visual contract

Use the unchanged `public/brand/logos/full-primary.svg`, `#FBB104` yellow, `#0A0A09` black and bright white surfaces. Display/navigation use Heebo; body text uses Assistant. Buttons have 16px corners and 56/44/36px heights. The actual molded shadows are exported from `app/globals.css`; do not recreate the style from a screenshot or old ZIP.

Heebo, Assistant and Noto Sans Arabic load externally through Google Fonts; font binaries are not bundled. See `HANDOFF_READINESS.md` for asset and font delivery requirements.

Use the shared `KButton`, `KChoiceCard`, `Tabs`, `PlansMenu`, `DiscoverySearch` and `ListingPhoto`. Ordinary picture actions reveal after 600ms; featured pictures reveal immediately. Touch and keyboard access remain immediate. The loader only fills the original yellow bars; KLIGO text never moves or disappears into the bars. The screen has reduced-motion, no-JavaScript and stalled-hydration escape behavior.

## Demo state and production contracts

This is a presentation and interaction reference, with fictional listings and illustrative prices. It is not a live commercial marketplace backend.

| Domain | Working reference | Production replacement |
| --- | --- | --- |
| Inventory | `listing-session.ts`: draft/published/paused; published records appear in the current tab's marketplace | Authenticated listing API, ownership, validation, pagination and moderation |
| Photos | Browser uploads resized before session storage; credited representative seed images | Object storage, upload limits, scanning, EXIF handling, thumbnails and signed URLs |
| Companies | Canonical company routes plus current local company preview | Company API with membership roles and verification evidence |
| Requests | Selected company/listing retained through request entry and review | Durable request records with recipient IDs, server state transitions and authorization |
| Saved items | One persistent browser shortlist; removal/undo and legacy migration | User-owned favorites API, device synchronization and deleted-listing handling |
| Messages | Correct company thread; existing history retained in the browser tab | Authorized conversations, real delivery, attachment storage and unread synchronization |
| Plans/billing | Accessible Plans menu; sample subscription and invoice screens | Payment provider, hosted checkout, webhook verification, idempotency, invoices and cancellation |
| Advertisements | Shared placement catalog, visible VAT-inclusive totals, descriptions and examples | Server-authoritative price book, placement capacity, scheduling and delivery |
| Analytics | Demonstration reports | Event definitions, consent, attribution, deduplication and aggregate APIs |
| Map | MapLibre street map; approximate Israeli pickup areas; four adjacent results | Approved tile/geocoding service; retain attribution and confirm service limits before launch |
| Reviews | Actual available sample records drive averages, counts, distribution, sorting and catalog rating filters | Server-owned reviews, eligible completed relationships, moderation, pagination and author privacy |
| Reporting | Company-specific contact gate and unsent report drafts in this tab | Authenticated server-side relationship checks, canonical listing ownership, rate limits, moderation and secure evidence uploads |
| Identity/support | Profile forms and demonstration support flows | Authentication, password/session lifecycle, verified contacts and a support queue |

Persist canonical IDs (`companyId`, `listingId`, `requestId`, `conversationId`) on the server. Never trust browser prices, subscription flags, verification badges or claims of ownership. Keep photos and messages outside analytics payloads. Local listings never receive invented street coordinates. Supported cities can use existing approximate city-level pins; unknown cities remain as result cards without pins.

## Web and mobile architecture

### Compact listings and local ad placement

`ListingCard` is shared by discovery, company inventory, saved grids and homepage cards. `ListingGallery` composes the installed carousel and defers distant slides. It preserves direct photo links, suppresses offscreen tab stops, supports RTL/arrow keys and reduced motion, and never creates duplicate slides to imply more photos. Four catalog examples include their already-approved white-background edits; provider uploads retain their actual gallery. Single-photo records remain single-photo cards.

Equipment grid/list pagination uses eight results; maps keep four. Local listings join filtered discovery results. `capSponsored` allows at most one sponsored card in any consecutive eight entries, before pagination, while retaining every eligible record. `activeListingCampaign` checks active state, dates, canonical target and placement surface. This is browser-tab demo delivery, not shared production ad serving. The campaign store emits updates; pause/stop and expiry remove demo placement. Local home hero links return to the relevant inventory type; company/banner/category-sponsor delivery remains separate from listing promotion.

Local map campaigns require an existing supported city and a daily price. `localMapListing` uses the centre of that city's existing approximate catalog pickup points; these are explicitly city-level demo areas, never a claimed street address. Unknown locations receive no pin. Production must geocode and validate provider-authorized pickup/service locations server-side.

### Saved items, reviews and reports

`SavedWorkspace` retains one `saved-store.ts` collection in either grid/list view; `kligo:saved-layout` changes only presentation. `ProviderReviews` and `review-summary.ts` share source records with catalog summaries and rating filters. Do not import legacy numeric catalog ratings as customer proof. Empty review collections show no rating; illustrative reviews remain labelled as demo feedback.

`contact-history.ts` records explicit outgoing demo messages and completed provider-specific equipment/service requests or supply quotes. Opening a company, marking a conversation read, preparing a contact form, saving a draft or loading seeded messages never establishes contact. `/report` and `/provider/trust/report` both use `ListingReportForm`. Targets resolve from canonical catalog/profile data, including published local inventory; arbitrary query titles, provider labels and contact flags are ignored. The report save handler rechecks contact, validates details and keeps unsent drafts/filenames in session storage with visible recovery history. Storage failures retain form text and do not claim delivery.

This client gate is a prototype interaction, **not an authorization boundary**. Before real reporting, authenticate the reporter on the server; load the listing and owner from trusted records; verify the reporter's actual conversation/request/booking relationship with that owner; enforce self-report rules, rate limits and duplicate policy; and store audit evidence for moderation. Both web and mobile must call that same server policy. Do not accept client contact flags or payment as proof. Report drafts, support messages, payments and badge applications in this demo are not delivered to operational services.

Use one authenticated, versioned API for both clients. Keep domain schemas, validation rules, prices and state transitions independent of React. Implement mobile screens against the same contracts; React DOM components themselves are web-specific. Separate inventory/media, company membership, requests/quotes/bookings, messaging, billing and campaign reporting. Introduce queues for image work and notifications as actual load requires; avoid speculative service splitting before measuring usage.

## Languages and accessibility

`translateInterfaceChildren` preserves single React-element children, refs and handlers so Radix `asChild` compositions remain valid. The shared Plans menu composes `DropdownMenuItem → KButton → Link`; do not replace the link with an array or add nested buttons. All role headers use this menu. Ad-type changes carry the chosen listing ID and duration in the URL while intentionally dropping edit/renew identity so a different campaign is never overwritten. Missing listing IDs require a fresh choice.

Shared navigation, actions, tabs, form labels and discovery controls use the locale context. The calendar uses the selected locale and RTL direction. English is the fallback for copy without a translation, including some long demonstration descriptions. Before a multilingual public launch, commission native Hebrew/Arabic review of all remaining editorial copy, legal text and notifications; never machine-translate user-entered names, serial numbers or specifications implicitly. Keep logical spacing, visible focus, useful error messages and non-hover actions.

## Before accepting real customers

Mobile refinement batch 2: `MobileAppNavigation` is mounted once in the root layout and hidden on authentication routes. `MobileTopBar` replaces the old headers below 768px; tablet/laptop navigation is preserved. Role-aware links use exact `/provider` route boundaries so public `/providers/...` pages stay marketplace pages. Profile links expose account and workspace shortcuts. The profile editors hide inactive sections with mobile-only CSS while keeping fields mounted and drafts intact; desktop still shows the full forms. Safe-area offsets reserve room for tabs and save controls. Software-keyboard viewport changes hide the bottom tabs while editing. The Developer Kit uses the same exported navigation configuration.

Mobile refinement batch 1 uses breakpoint 768px: compact two-column categories and listing grids, a single column below 360px, short sponsored banners and company rows. Listing photos/titles remain direct links; the native Actions disclosure keeps quote/compare controls available without crowding the card. Mobile filters compose the existing Radix Sheet with a fixed submit action. Services, parts, materials and company discovery paginate eight results on mobile; equipment already uses eight. Desktop result counts/layouts stay as before. Browser visual QA remains outstanding. See `MOBILE_REFINEMENT_BATCHES.md` for the remaining app-preview work.

1. Connect and verify identity, ownership, persistent APIs, media storage and transaction services.
2. Confirm real subscription/ad prices, invoices, refund/cancellation behavior and payment webhooks.
3. Replace fictional data and representative photos with authorized inventory and verified company claims.
4. Test the real deployed integration on desktop and mobile, including keyboard, touch, RTL, slow networks, unavailable maps and denied storage.
5. Review localization, accessibility, privacy, retention, monitoring, backups, permissions and abuse handling with the responsible specialists.

`export-manifest.json` fingerprints the source included in the download. The deployed app regenerates downloads during each production build so the code and kit do not silently drift apart.