B2BEA.org Rebuild target-architecture-spec

Full legacy body rendered for humans

B2BEA.org V1 Target Architecture Spec

Source of record: RedKey Supabase Studio artifact.

• Project: B2BEA.org Rebuild
• Project ID: a820dd0c-6cef-4133-bfbd-d802fd806e44
• Artifact: target-architecture-spec
• Version: 2
• Status: draft
• Updated: 2026-05-08

Purpose

Define the technical shape required before implementation planning. This spec resolves the architecture decisions that the surface, data, entitlement, publishing, and design artifacts imply but do not yet fully specify.

Target Recommendation

Use a hybrid-first architecture.

Eleventy remains the public publishing engine for B2BEA.org fast public site. A dedicated application layer handles authenticated, permissioned, write-heavy, preview, export, and operational workflows.

This preserves Eleventy speed and simplicity where it is strongest while avoiding client-side-only authorization and page-specific workflow hacks for app surfaces.

Architecture Decisions

| id | topic | decision |

| --- | --- | --- |

| ARCH-DEC-001 | Public site renderer | Keep Eleventy for public static publishing: marketing pages, editorial, resources, topic/concept pages, public directory/profile pages where data can be generated or safely cached. |

| ARCH-DEC-002 | App/runtime layer | Use a dedicated app layer for authenticated/admin/member/vendor/company/auth workflows. Preferred implementation target is Next.js + TypeScript unless a thinner Cloudflare Pages Functions app proves sufficient during Slice 0. |

| ARCH-DEC-003 | Route surfaces | Public routes stay on B2BEA.org where practical. Private surfaces use canonical prefixes: /admin, /member, /vendor, /company, and auth/account routes. Public practitioner company profiles/directories remain excluded. |

| ARCH-DEC-004 | Route split | Prefer one domain with route-level split if Cloudflare routing is clean. Subdomains such as app.b2bea.org or admin.b2bea.org are acceptable only if same-domain routing becomes operationally brittle. |

| ARCH-DEC-005 | Data ownership | Sanity owns editorial/public page content. B2BEA Supabase owns operational/application records. HubSpot owns CRM/pipeline/sales/renewals. Access these through local adapters, not direct calls scattered through pages. |

| ARCH-DEC-006 | Authorization | Protected reads and mutations use server-side guards in the app layer or Cloudflare Functions. Client UI may hide controls, but never grants access. |

| ARCH-DEC-007 | Design system | Shared B2BEA design-system tokens/components govern both Eleventy public templates and app-layer surfaces. Custom pages must declare an exception and still pass QA. |

| ARCH-DEC-008 | Publishing preview | Public published pages remain static. Draft/preview/publishing control happens through the app layer, then publishes to the static public projection or approved custom route. |

| ARCH-DEC-009 | Testing | Slice 0 must establish public static checks, app route guard tests, component contract tests, and browser screenshot smoke tests before public migration begins. |

Public Eleventy Layer

Eleventy owns fast public delivery for home, standard marketing pages, audience landing pages, blog/editorial pages, podcast public pages, resources/guides/reports/case studies, topics/concepts, public vendor directory/profile pages, public people/profile pages, events, jobs, course previews, sitemap, public search index, static metadata, and GEO-ready content artifacts.

Eleventy may call build-time adapters for Sanity and safe public Supabase projections. It must not embed secrets or rely on client state for protected access.

Application Layer

The app layer owns /admin, /admin/studio, /member, /vendor, /company, login/signup/account utility routes when server-side auth control is needed, protected resource/course access decisions, submissions, review queues, exports, audit events, billing handoffs, preview, publish, archive, rollback, and custom HTML import registry workflows.

Proposed Module Boundaries

| module | responsibility |

| --- | --- |

| eleventy/src | Public static pages and reusable public templates. |

| eleventy/_data or equivalent | Build-time public content adapters with safe fallbacks. |

| app/src/routes/admin | Single B2BEA admin shell and publishing module. |

| app/src/routes/member | Member dashboard/account/profile/resource/academy surfaces. |

| app/src/routes/vendor | Private vendor workspace. |

| app/src/routes/company | Private practitioner company workspace. |

| packages/b2bea-design-system | Shared tokens/components/contracts usable by Eleventy and app surfaces. |

| packages/b2bea-auth | Session loading, role checks, entitlement checks, guard contract. |

| packages/b2bea-data/sanity | Sanity read/write/preview adapter. |

| packages/b2bea-data/supabase | Supabase operational data adapter. |

| packages/b2bea-data/hubspot | HubSpot CRM adapter. |

| packages/b2bea-metadata | SEO/GEO/social metadata generation and validation. |

| packages/b2bea-routes | Route registry, redirects, sitemap/search index inclusion. |

| packages/b2bea-audit | Audit/event logging for material protected actions. |

Guard Pattern

Every protected route/action must produce a traceable access decision with allowed, subjectId, subjectRoles, resourceType, resourceId, entitlementKey, reason, and source.

Adapter Rule

Templates, pages, and components must not directly import external SDK clients. They call local services/adapters so tests can stub Sanity, Supabase, HubSpot, Stripe, email, and Cloudflare behavior.

Slice 0 Output

Slice 0 should establish confirmed repo/workspace layout, route registry with public/static versus app/protected ownership, shared B2BEA tokens/components, server-side guard helper and tests, metadata validator stub and tests, data adapter interfaces, redirect and sitemap/search-index classification, and screenshot smoke harness for representative public and app shell routes.

Open Decisions

| id | decision | required_before |

| --- | --- | --- |

| ARCH-OQ-001 | Confirm the app-layer technology: Next.js + TypeScript, Remix, or thinner Cloudflare Pages Functions app. | Slice 0 plan |

| ARCH-OQ-002 | Confirm whether route-level split on b2bea.org is clean enough, or whether private surfaces should move to subdomains. | Slice 0 plan |

| ARCH-OQ-003 | Confirm workspace layout: one monorepo with Eleventy/app/packages, or current Eleventy repo plus separate app repo/package. | Slice 0 plan |

| ARCH-OQ-004 | Confirm whether Sanity write operations occur inside the app layer or through a separate admin function/service. | Slice 2 plan |

Acceptance Criteria

• Eleventy remains in the architecture for public speed and static SEO/GEO publishing.
• Authenticated/private/write-heavy surfaces are not forced into client-only static-page behavior.
• Protected actions and data reads have one shared server-side guard pattern.
• Data ownership maps to adapters, not scattered SDK usage.
• Slice 0 can be planned without deciding every page migration detail.