# HTS Marketplaces Engine — Architecture Assessment *Prepared for HomeTown.Social · A planning document, not a build* *Status: strategic assessment — no code has been written or changed* --- ## What this document is You asked three things: help decide whether this engine replaces or joins the current marketplace, treat it as a future bet to plan now and build later, and above all tell you straight how to do it **without breaking what works.** This document answers those. It is deliberately honest about cost and risk, because a system this size punishes optimism. Nothing here has touched the live platform. --- ## The one-paragraph summary The Marketplaces Engine you've specced is a genuinely good design and the right long-term direction for HomeTown.Social. It is also the largest single thing the platform would ever have taken on, and it is **not safe to build on today's foundation as-is.** The current architecture — one large HTML file, data mirrored to Supabase in whole-array broadcasts, security at the app layer — has been the direct cause of the "saves locally but not to the server" bugs you fought all through the last session. This engine would multiply that exact class of bug. The path forward is real but sequenced: fix the foundation first, build the engine second, and keep the current marketplace running untouched the entire time. --- ## Part 1 — The decision: replace or run alongside? **Recommendation: run alongside first, absorb later. Never hard-replace.** Here is the reasoning, because the answer isn't obvious. The current marketplace works. It has real listings, working photos, edit, links, contact, community filtering, and a public preview. It took a full session to stabilise. Throwing that away to make room for the engine would be trading a working thing for a promise. But the engine and the current marketplace are not really the same kind of object. The current one is a **single flat marketplace**. The engine is a **framework for many marketplaces**. The clean way to think about it: when the engine is real and proven, today's marketplace becomes *one marketplace inside it* — most likely the "Consumer Marketplace" or a "HomeTown Classifieds" node. It gets absorbed, not deleted. So the sequence is: 1. Engine is built as a **separate, parallel system** — its own tables, its own admin, its own member view. The current marketplace keeps running, completely untouched. 2. Once the engine is proven with a real marketplace (the Business slice), you make a calm decision about migrating the current listings into it. 3. Only when migration is tested and you're happy does the old marketplace retire. At no point is there a moment where the working thing is gone and the new thing isn't ready. That's the whole game. --- ## Part 2 — Can the current architecture hold this? (The honest answer) **Not as it stands. Here's exactly why, in plain terms.** ### The sync model is the blocker Today, when any record saves, the app doesn't send just that record — it broadcasts the **entire local copy of that data type** to the server. You saw what this causes: a stale copy overwriting a fresh edit, roles vanishing, settings reverting, the timestamp-guard fix we had to add mid-session. Now scale that to the engine. A marketplace tree has hundreds of nodes. A listing can sit in many nodes at once (many-to-many placements), which means a *separate* set of placement records, potentially thousands of them. If those save with the same broadcast-all pattern, you get the vanishing-data bug — but now on the structure that organises your entire marketplace. A node quietly reverting to a different parent would reshuffle navigation for every visitor. **This is not a reason to abandon the engine. It's the reason the foundation must be fixed first.** The broadcast-all cleanup is already item #1 on your weekend list. It stops being a nice-to-have and becomes a prerequisite. ### The single-file model strains, but survives 21,000 lines in one file is already at the edge of comfortable — we deleted a function by accident twice in one session just editing near things. The engine adds admin tree builders, recursive renderers, breadcrumb logic, placement management. That's thousands more lines. This is survivable but argues strongly for the engine living in its **own file or files**, loaded alongside the platform rather than crammed into `hts.html`. This also happens to be exactly the App Library / standalone-page thinking you've already been circling. The engine is a natural first real tenant of that pattern. ### The database needs to become genuinely relational Today's Supabase tables are mostly flat and independent — a `posts` table, a `profiles` table, each a bag of rows. The engine needs **real foreign-key relationships**: nodes pointing to parent nodes, placements linking listings to nodes, cascade rules on delete. That's a more disciplined relational design than anything currently in your database. Supabase (Postgres underneath) handles this beautifully — it's what Postgres is *for*. But it means the engine's data layer would be built to a higher standard than the current app, and the two would coexist rather than share patterns. That's fine, even healthy, but worth knowing. --- ## Part 3 — The safest data model The model in your brief is sound. I'd keep its four-table shape — marketplaces, nodes, listings, placements — with a few integrity refinements. The key decisions: **Nodes are self-referencing.** A node has a `parent_node_id` pointing at another node (or null for a root). This is the standard, proven way to get unlimited depth. It needs guards against circular references (a node can't become its own ancestor) — cheap to enforce, essential to include. **Placements are the many-to-many bridge.** A listing never lives "in" a node directly. Instead a `placement` record says "listing X appears in node Y." One listing, many placements, appears in many places, but there is only ever **one listing record** — so editing it updates everywhere at once. This is the single most important structural choice in the whole design and your brief gets it right. **Marketplace-specific fields go in a flexible `metadata` column, not new columns per marketplace.** Real estate needs bedrooms; automotive needs mileage. Do NOT add columns for these to the shared listings table — that way lies a table with 200 columns, 190 of them empty. Instead store a JSON `metadata` blob per listing and let each marketplace define which fields it expects. Postgres handles JSON natively and can even index into it. This is the "configurable field schema" your brief asks about, and it's the safe scalable answer. **Everything soft-deletes.** Nothing is ever truly removed — it gets a `deleted_at` stamp and disappears from view. Given how much data went missing to silent sync failures last session, hard deletes on a tree structure would be genuinely dangerous. Soft delete means a mistaken node deletion is always recoverable. --- ## Part 4 — Phased implementation plan Each phase is a stopping point. You can pause after any of them with a working platform and decide whether to continue. That's the discipline that protects you. ### Phase 0 — Foundation (prerequisite, no engine yet) Fix the broadcast-all sync problem. Move to per-record saves with the timestamp-guard approach already proven on profiles. This is on your weekend list regardless. **The engine should not begin until this is done** — building on the current sync model would bake the vanishing-data bug into the marketplace structure itself. ### Phase 1 — Data foundation (invisible to members) Create the four tables in Supabase with proper relationships, constraints, and soft-delete. Build the read/write layer. No UI yet. Nothing visible changes on the live site. This proves the data model holds before a single screen is built. ### Phase 2 — Admin tree builder (admin-only) The interface to create a marketplace, add nodes, nest them, reorder, move, publish, hide, and soft-delete — with the safeguards (no circular refs, no orphans, no deleting a node with children without confirmation). Admin-only, invisible to members. This is where the engine becomes real. ### Phase 3 — The vertical slice (the proof) Build exactly the example from your brief: Business → Technology → AI → AI Writing Tools → ChatGPT. One marketplace, one deep branch, one real listing. Member-facing browsing, breadcrumbs, responsive display. This proves the whole concept end to end on real data. **This is the milestone that tells you whether to keep going.** ### Phase 4 — Member experience polish Filters, search, featured listings, saved listings, empty states, the marketplace selector. The things that make it pleasant rather than merely functional. ### Phase 5 — Migration decision Only now, with a proven engine, decide what to do with the current marketplace. Migrate its listings in as a node? Keep it separate? Retire it? You make this call with full information and zero pressure, because everything still works. ### Phase 6 — Expansion (no code) Once the engine is proven, new marketplaces and categories are created through the admin, not through code. Discovery, Real Estate, Jobs — all become configuration, not development. This is the payoff the whole architecture exists for. --- ## Part 5 — Risks, stated plainly **The biggest risk is scope, not code.** The brief lists a dozen future marketplaces and dozens of node types. The failure mode is trying to honour all of it at once. The discipline is: build the engine, prove it with *one* small slice, expand through admin. Your brief already says this — it just has to be held to under the excitement of a working system. **The second risk is building on unfixed foundations.** Covered above. Phase 0 is not optional. **The third is the single-file strain.** The engine wants its own home. This is an opportunity, not just a risk — it's the forcing function for the modular architecture you already want. **The fourth is time.** This is not a session or a weekend. Realistically it is a multi-week project even done well and in order, with Phases 0–3 being the bulk of it. That's not a discouragement — it's the honest number, so you can plan around it rather than be surprised by it. --- ## Part 6 — What I'd tell you if you asked "should I?" Yes — but not yet, and not fast. This is the right direction. It matches the "Community Operating System" ambition in your licensing vision, it turns your marketplace from a feature into a platform, and the many-marketplaces-one-engine design is genuinely well conceived. Nothing in the brief is wrong-headed. But it earns its place *after* the foundation is sound and the current platform is stable and growing. Build it when you have the runway to do Phases 0–3 properly, in order, with testing between each — not as the next thing squeezed onto the end of a long night. Plan it now. That's what this document is for. Build it when the foundation can hold it. --- *One dynamic engine. Multiple marketplaces. Unlimited organization. No hard-coded category structure — resting on a sync layer that can actually carry it.*