# ARCHITECTURE.md — what exists > Factual map of the actual system, from auditing both repos. **Built vs PLANNED > is marked explicitly** — anything labeled PLANNED does NOT exist yet, do not > imply it does. For the full security analysis see > `handoff-blocks/audits/architecture-security-audit-2026-06-01.md` (referenced, > not restated here). Companion: `PRINCIPLES.md` (how/why). Update at the moment of > decision; per-decision rationale goes in `docs/adr/`. --- ## 1. The two repos ### A. `samesolutionsllc-website` — public site + PWA + admin app - **GitHub:** `SUGARDUNK3RTON/samesolutionsllc-website` — **PUBLIC**. - **Serves:** `samesolutionsllc.com` (Cloudflare auto-deploy on push to `main`). - **Stack:** hand-authored static HTML, **no build step** (`package.json` only pulls Playwright for smoke tests). - **Contents:** - `index.html` — public marketing landing (~455 lines). - `manage/index.html` — the business-management **PWA**, ~28K-line single file (HTML+CSS+JS); Firebase Auth + Firestore wired; APP_VERSION ~v1.7.22. - `manage/sw.js` — service worker (cache ~v58); `manage/manifest.json` (`start_url: /manage/`). - **Tests/CI:** Playwright smoke tests run against production via GitHub Actions on push (`.github/workflows/smoke-test.yml`). ### B. `samesolutions-equipment-service` — the substrate (hub + knowledge base) - **GitHub:** `SUGARDUNK3RTON/samesolutions-equipment-service` — **PRIVATE**. - **Serves:** `samesolutions-equipment-service.pages.dev` (Cloudflare **Pages**, auto-deploy on push). PWA "Same Solutions Hub", `manifest.json` `start_url: "/"`. - **Stack:** static HTML **+ Cloudflare Pages Functions** (`functions/`): KV-backed auth API (PBKDF2 + sessions), `/our/data` KV store, `/handoff` endpoints, calendar, bets fetchers, Google OAuth. ## 2. Substrate taxonomy (where things live) | Path | Holds | |---|---| | `guides//` | Equipment service guides (fourwinns-h190, harris-flotebote-pontoon, lt180, seadoo-gtx-di-2001; yamaha-f150tlr = a **customer** engine, John Lubig's). **Common look (2026-06-03): the canonical theme is the Lubig/Letvin `.card` structure + the LIGHT palette (`--bg #fafaf7`, `--accent #FFB612`, no gradients). Service guides are migrating to that light palette (Sea-Doo done as the reference; LT180 + structural alignment pending) — see `handoff-blocks/audits/guide-template-commonization-2026-06-03.md`.** | | `index/equipment/.md` | Equipment dossiers (entity index) | | `index/personal-project/.md` | Personal-project index entries | | `personal/` | Sam's personal hubs — calendar, status-tracker, ai-hub/career, 3d-printing, financial-planning, equipment (soft-fenced) | | `customer-jobs//` | Customer work (lubig-bennington, aceves, letvin, peter-scott...) | | `handoff-blocks/` | Coordination, audits, patterns, architecture decisions, session reports | | **`data/issues.json`** | **CANONICAL issues registry** (~75 items: id/title/priority/status/category/severity). Consumers: hub badge, `/personal/issues/`, and the status-tracker dashboard/issues/current views. The old 66-item `status-tracker/issues.json` was merged in + retired 2026-06-02. | | `sitemap.html` | Manual file-discovery index (hub -> sitemap -> file) | | **`awareness-backlog.md`** | Single cross-session board; contains the fenced **`SAMEING-NOW`** JSON block that drives the hub command deck | | `/our/`, `/win/`, `/cece/`, `/jon/` | Per-person hubs (soft-fenced; `/jon/` has the customer-registration session auth) | | `PRINCIPLES.md`, `ARCHITECTURE.md`, `METHODOLOGY.md`, `SESSION-PRELUDE.md`, `SYSTEM-DESIGN.md` | Governance / methodology | | `docs/adr/` | Architecture Decision Records (home established; see its README) | ## 3. PWA / entry surface - Substrate hub PWA `start_url: "/"` -> opens the hub `index.html`, whose top panel is **SAMEing Now** — the single operational command deck, rendering live from the `SAMEING-NOW` block in `awareness-backlog.md` (active_now / cc-status / planning pings / editable buttons + a "My Documents" doc-nav). It consolidated three prior status surfaces (the hub tile + status-tracker `current.html` + `dashboard.html`). - The website `/manage` PWA is a separate install (`start_url: /manage/`) opening to the business Dashboard. ## 4. Data / auth model ### AS-IS (today) — see the security audit for detail - **`/manage`:** all business data lives in **one Firestore document** (`businesses/same-solutions`); per-user "scoping" is **client-side cosmetic filtering** — the full blob reaches the browser before any role check. Signup is open (`createUserWithEmailAndPassword`). - **Substrate:** a **client-side soft-fence** (`auth/gate.js`) only — there is **no `functions/_middleware.js`**, so static pages are served to anyone with the URL. `/our/data` is now **session-gated, fails closed** (but Sam/CeCe have no real sessions yet, so it 401s). `/jon/` has real KV-session auth (the customer- registration backend: PBKDF2, invite-gated, 30-day sessions). - **Net:** UI scoping is not access control. PII must not land on these surfaces. ### PLANNED — NOT YET BUILT (do not imply it exists) - **Customer product:** per-customer **Firestore documents** + real **security rules** + **invite-only signup** (re-model the single blob into per-customer docs). - **Private substrate hubs:** **Cloudflare Access** (or a fail-closed `_middleware.js`) gating `/personal`, `/win`, `/cece`, customer-job dossiers. - These are the audit's recommendation; none are implemented. ## 5. Known issues / tech debt (factual) - **Git history retains removed PII.** The cece-taxes guide + report files + figures were removed/redacted from HEAD, but git history still contains them. History scrub is a pending Sam decision; the substrate repo being PRIVATE limits exposure. - **The website repo is PUBLIC on GitHub.** `manage/index.html` previously embedded customer PII + a base64 password scheme (scrubbed from HEAD; customer surnames still survive in data-key IDs; history retains the originals). **Repo-private + credential-rotation decisions are pending.** - **The Firebase security rule on `businesses/same-solutions` is UNREAD** (console- only). It is the single biggest unknown in the security posture — verify it. - **Cloudflare deploy/edge cache:** deletions have lagged promotion and needed an explicit cache **purge** to clear live (a takedown isn't done until the live URL 404s — see PRINCIPLES §4). - **No dedicated backup branch** of the substrate exists. [PROPOSED: worth adding; confirm with Sam.] - **`/guides/*` routing** has had intermittent behavior; do not change it without confirming it isn't currently shielding something. --- — ARCHITECTURE.md created 2026-06-02 by CC from the two-repo audit. Built-vs-PLANNED is current as of this date; update at the moment of decision.