1. Architecture Overview

Koinetic is a multi-tenant operating layer — a structured CMS + directory backend that powers many independent properties from one private control plane. The hierarchy:

PlatformPlan
 └── Builder (org / customer)
      └── App (one app per builder)
           ├── Site(s)   → Domain(s)     ← how requests are routed
           ├── Settings   (theme, SEO, social)
           ├── Categories → Listings
           ├── Pages      (CMS)
           ├── Articles   (Blog)
           ├── PricingTiers → TierFeatures
           ├── Forms → FormSubmissions
           ├── ContentTypes → ContentFields → ContentRecords
           ├── Reviews
           ├── Notifications (banners)
           ├── LegalSnippets
           ├── NavigationMenus
           ├── Webhooks
           ├── Media
           ├── EmailTemplates
           ├── Claims
           ├── Contacts
           ├── Blueprint? → Vertical data model (field schema, sub-directories, monetization)
           └── Template?  → Sections, Theme, PageLayouts

Key Concepts:

• Each Builder has exactly one App.
• Each App has one or more Sites, each with one or more Domains.
• The incoming request's Host header determines which App's data is served.
• All public endpoints are read-only except a small set of writes: reviews (POST), forms (POST), contact (POST), claims (POST), marketplace inquiry (POST).
• Nothing is open by default. Most endpoints require a scoped tenant API key (X-API-Key). A small, deliberately chosen set of endpoints is keyless because it is public-safe by design (see §2.1) — those are resolved by host and are still rate-limited.
• Every endpoint — keyed or keyless — is subject to per-IP (and, where applicable, per-key/per-app) rate limiting; excess traffic receives 429 (see §8).
• For keyed endpoints, include X-API-Key: gao_xxxxxx with every request.

Vertical Blueprints (the data-model layer)

A Blueprint is a platform-level recipe for a vertical. The currently available verticals are:

Where a Template owns presentation (sections, theme, layout), a Blueprint owns the data model:

• a typed field schema (fieldGroups) that describes the structured fields living inside each Listing's metadata JSON — e.g. tradingFeeSpot, supportedCoins, bedrooms, startingPrice. Each field declares its control type, whether it appears on cards, in the comparison table, as an auto-generated FAQ, and how it maps to schema.org structured data.
• a schema.org @type (e.g. FinancialProduct, RealEstateListing, SoftwareApplication) used for listing JSON-LD.
• a monetization engine (affiliate, lead_gen, listing_fees, community).
• a composition describing page archetypes and nested sub-directories (e.g. electricians / HVAC under Real Estate), each of which can borrow another blueprint's schema.
• default categories seeded when a site adopts the blueprint, and a usesGeo flag enabling location search.

A Blueprint is a lens over the existing Listing model — no Listing data is migrated. The same field schema drives the Add-Listing form, the comparison table, storefront filters/sorting, the dynamic FAQ accordion, and the additionalProperty[] loop in listing JSON-LD, with zero per-vertical code. An App may be assigned one Blueprint (App.blueprintId); when none is set, the Generic blueprint applies.

Each Blueprint also carries vertical-appropriate demo data used by the sample-content seeding flow: defaultCategories, defaultPricingTiers, and defaultListings (8–10 listings for real, recognizable businesses in that vertical whose metadata already conforms to the vertical's fieldGroups). Seeded listings and articles are created already published (not draft), so a freshly seeded property renders as a complete, live site with no per-entry activation step. This guarantees that pricing and sample listings are vertical-correct at the data layer — every API consumer (including fully custom/headless front ends) automatically receives the right pricing tiers and real sample listings for its vertical, with no front-end logic required. A crypto property never sees home-services pricing, and a home-services property never sees crypto listings.