surface-specs · supabase_json
B2BEA.org V1 Surface Specs
surface-specs artifact · for B2BEA.org Rebuild · status approved
Agent Handoff
Start Here
surface-specs artifact · for B2BEA.org Rebuild · status approved
Completion Evidence
- Each V1 surface has named actors, purpose, route families, page families, data sources, required patterns, exclusions, and acceptance checks.
- Surface boundaries align with current design, publishing, data, entitlement, and company-workspace specs.
- Page-template-spec can be produced from this artifact without resolving major surface ownership questions.
- Implementation agents can tell whether a route belongs to public, auth/account, admin, publishing/studio, member, vendor, or company workspace.
- All P0 public/private exposure decisions are explicit, especially vendor public profiles versus private practitioner company workspaces.
Artifact Shape
- basis: 4 items
- title: B2BEA.org V1 Surface Specs
- status: draft
- purpose: Define the concrete public, admin, member, vendor, company, auth, and publishing surfaces that implementation must build against after the current-site reverse-engineering and hardening specs.
- version: 1
- project id: a820dd0c-6cef-4133-bfbd-d802fd806e44
- updated at: 2026-05-07T15:35:22.233Z
- updated by: atlas-codex
- artifact type: surface-specs
- revision note: Linked draft survey-system-spec artifact.
- next artifacts: 7 items
- surface catalog: 7 items
Structured Payload
Machine-readable source fields
basis
- Current-state research artifact maps existing Eleventy/Nunjucks layouts, partials, routes, and surface roles.
- Capability map identifies carry-forward and gap capabilities across public, admin, member, vendor, and company workflows.
- Design-system spec uses Lovable as the initial foundation/reference, while the hardened B2BEA design system is the V1 authority for non-excluded surfaces.
- Publishing, data, entitlement, and company-workspace specs define source-of-truth and lifecycle boundaries.
title
B2BEA.org V1 Surface Specs
status
draft
purpose
Define the concrete public, admin, member, vendor, company, auth, and publishing surfaces that implementation must build against after the current-site reverse-engineering and hardening specs.
version
1
project id
a820dd0c-6cef-4133-bfbd-d802fd806e44
updated at
2026-05-07T15:35:22.233Z
updated by
atlas-codex
artifact type
surface-specs
revision note
Linked draft survey-system-spec artifact.
next artifacts
- qa-release-readiness-spec
- plan
- sanity-schema-spec
- custom-html-import-spec
- notification-spec
- academy-certification-spec
- vendor-portal-workflow-spec
surface catalog
| id | name | actors | purpose | acceptance | exclusions |
|---|---|---|---|---|---|
| public_site | Public Site | - anonymous_visitor - authenticated_member - vendor_prospect - practitioner_prospect - search_engine - ai_crawler | Marketing, editorial, discovery, directories, resources, academy previews, events, jobs, public people profiles, and public vendor profiles. | - Each public route maps to one page family or an approved exception. - Public vendor profiles render from reviewed/published vendor projection only. - Protected resource/course access is checked server-side through entitlement rules. - Directory filters, search, and cards share one reusable contract across people/vendors/jobs/courses/resources where practical. - Archived or draft public content is absent from navigation, search index, and sitemap. | - public practitioner company profile pages - public practitioner company directory - ungated protected resource downloads through client-side state only |
| auth_account | Auth And Account | - anonymous_visitor - authenticated_user - member - vendor_user - company_user - admin | Login, signup, email confirmation, password/magic-link/OAuth, account routing, and shared access failure states. | - A user with multiple roles can reach the correct surfaces without role overwrite. - Account and membership status is explainable from entitlement evaluator output. - Client state cannot grant protected resource/course/vendor/company/admin access. | |
| b2bea_admin | B2BEA Admin | - justin - brett - sarah - b2bea_admin | Single authenticated admin control plane for operational records, review workflows, publishing/studio modules, users, vendors, companies, academy, jobs, categories, media, dashboard metrics, and system governance. | - Admin pages do not use large public marketing hero patterns. - Every reviewable external submission has status, owner, timestamp, decision, and audit trail. - Admin direct-publish capabilities are limited to core admins and still require metadata validation. - Admin can see why a member/vendor/company has access before changing entitlements. | |
| admin_publishing_module | Admin Publishing Module | - justin - brett - sarah - content_admin | Publishing/content production module inside the single /admin shell. | - Core admins can publish standard Sanity pages without developer intervention. - Custom HTML import cannot bypass header/footer/metadata rules unless explicitly marked full-custom. - Every published item has canonical URL, metadata, preview evidence, and rollback/archive path. | |
| member_portal | Member Portal And Profile | - member - pro_member - author - community_leader | Member dashboard, profile/account editing, member/pro resources, academy progress, community identity, and career profile management. | - Members see only their own profile/account/progress data unless data is intentionally public. - Pro member and standard member access are visibly and server-testably different. - Profile visibility settings control public projection and search exposure. | |
| vendor_portal | Vendor Portal | - vendor_admin - vendor_member - b2bea_admin | Vendor workspace for profile management, team access, leads, sponsorship/content/resource/course/event submissions, and own-account analytics. Public vendor profile remains public but reviewed. | - Vendor-authored changes do not alter public profile until reviewed by B2BEA admin. - Vendor users cannot access another vendor account by URL or client state changes. - Exports are bounded to own-account aggregates and permitted lead details only. - Public vendor profile URL and metadata remain stable across private workspace edits. | |
| company_workspace | Practitioner Company Workspace | - company_admin - company_employee - b2bea_admin | Private company account surface for employees, seats, academy assignments, company-created job submissions, entitlements, and own-company reporting. | - No practitioner company workspace data is exposed on a public profile route in V1. - Company admins can invite/remove employees and seat access changes affect entitlements through the evaluator. - Company-created jobs cannot become public without B2BEA admin approval. - Company exports include only own-company data and exclude platform-wide comparisons or sensitive user-level data unless explicitly consented and permitted. | - public company profile pages - public company directory - company-owned CRM pipeline |
global decisions
| id | topic | decision |
|---|---|---|
| SURF-DEC-001 | Surface separation | Public, auth/account, B2BEA admin, publishing/studio, member, vendor, and practitioner company workspace are separate surfaces sharing foundations, not one large page set. |
| SURF-DEC-002 | Company public presence | Practitioner company accounts are private workspace only in V1. Do not build public practitioner company profiles or a public practitioner company directory. |
| SURF-DEC-003 | Vendor public presence | Vendor public profiles and vendor directory remain V1 public surfaces. Vendor-authored/profile changes require B2BEA review before changing the public projection. |
| SURF-DEC-004 | Design language | All in-scope surfaces use hardened B2BEA design-system component contracts. Home, intentionally editorial blog/resource pages, and approved custom HTML imports may be exceptions but still require accessibility, metadata, responsive, and QA compliance. |
| SURF-DEC-005 | Source of truth | Sanity owns editorial/public page content; B2BEA Supabase owns application and operational data; HubSpot owns CRM/pipeline/sales activity and renewals. |
| SURF-DEC-006 | Publishing control | Core admins can publish standard Sanity pages and approved custom HTML imports after preview and required metadata validation; external/vendor/company submissions route through review workflows. |
linked artifacts
qa release readiness spec
id
b523c55c-a22a-4ba6-94c0-d306656e57f7
version
1
shared contracts
design
- Use B2BEA design-system tokens and page/header/control/card/table/form contracts for all in-scope surfaces; Lovable remains the starting reference only.
- Admin/portal surfaces use compact operational hierarchy, not public marketing heroes.
- Cards do not nest inside decorative cards; tables and filters use stable dimensions on mobile.
- Exceptions require explicit page family marker and still pass accessibility/responsive/metadata QA.
navigation
- Public nav must not expose private workspace routes unless authenticated and entitled.
- Admin/vendor/company/member surfaces use surface-specific navigation with a clear return path to public site.
- Cross-surface links preserve return URL when auth is required.
permissions
- Server-side guard is required for all protected actions and protected data reads.
- Client UI can hide controls but cannot be the source of authorization.
- Entitlement decisions must be traceable to subject, resource, entitlement key, source record, and reason.
state model
- Every data-backed surface defines loading, empty, error, unauthorized, expired, draft, published/active, archived, and deleted/removed states as applicable.
- External submissions use review statuses instead of direct public mutation.
- Archived records are hidden from public discovery by default.
publishing and metadata
- Every public route has a canonical URL and metadata contract.
- Draft/preview/scheduled content is not indexed or linked publicly.
- Slug changes require redirect handling.
- Custom HTML imports must declare owner, route, status, metadata, asset bundle, preview URL, and rollback/archive path.
source artifacts
| id | status | version | artifact type |
|---|---|---|---|
| 0555c2b6-6f1f-41e5-bacb-7ca169b32fd5 | draft | 1 | blueprint |
| c889a1fe-c3ce-4b0d-873c-af4e0ec8dfe4 | draft | 5 | capability-map |
| 05e0ed7c-416a-4d8f-853a-bc3dfa3d64f6 | draft | 1 | company-workspace-data-spec |
| 2f473004-9063-4fe9-8290-5cbd1b19dfb4 | draft | 1 | data-model-spec |
| 4c3651ac-9a69-4117-a355-750b61f540c9 | draft | 2 | design-system-spec |
| 355b3249-3af9-45a4-9c45-67777bd2d72d | draft | 1 | entitlement-model-spec |
| a7044f26-904f-430a-a3c6-219f392c3a2b | draft | 1 | feature-ux-spec |
| c97be414-3dde-4085-9f57-fc38632d2de0 | draft | 1 | intent |
| dcfc8620-9f28-4019-aeeb-de3e279fd7a7 | draft | 3 | permission-lifecycle-matrix |
| 80328220-3deb-4cf9-a68f-d440b41a38da | draft | 3 | production-readiness-gap-register |
| a9636e2f-a4be-4586-82dd-c1a7bf3199fa | draft | 1 | publishing-model-spec |
| f6210edd-8414-41e9-a5d2-2e3d49ae4b18 | draft | 2 | research |
surface decisions
| id | topic | status | decision | rationale | decided at |
|---|---|---|---|---|---|
| SURF-OWNER-DEC-001 | Custom versus B2BEA design-system page treatment | approved_direction | Home, major campaign/resource landing pages, approved custom HTML imports, and explicitly marked signature editorial features may stay custom. All index, directory, search/filter, standard detail, gated download, operational, and authenticated surfaces use the hardened B2BEA design system. | This preserves flexibility for high-value custom storytelling while preventing the rebuild from recreating page-by-page drift across reusable page families and operational surfaces. | 2026-05-07T13:33:47.840Z |
| SURF-OWNER-DEC-002 | Private workspace route prefixes | approved_direction | V1 private workspace prefixes are /vendor for vendor users and /company for practitioner company users. Both are authenticated surfaces. /company has no public company profile or public directory behavior in V1. | Short actor-aligned prefixes are clearer than /portal/vendor or /workspace/company and avoid implying a generic portal architecture before it is needed. | 2026-05-07T13:35:10.892Z |
| SURF-OWNER-DEC-003 | Admin and publishing shell structure | approved_direction | V1 uses a single authenticated admin shell. Publishing/Studio is an admin module inside /admin rather than a separate top-level /studio shell. | B2BEA admin users can manage operations and publishing from one control plane. This reduces navigation fragmentation while preserving publishing-specific workflows and components as a distinct module. | 2026-05-07T13:35:53.103Z |
| SURF-OWNER-DEC-004 | V1, deferred, and removed route classification rule | approved_direction | V1 keeps the public content/discovery/membership surfaces, auth/account surfaces, a single /admin shell, /vendor private workspace, /company private workspace, and member profile/dashboard surfaces. V1 defers public practitioner company profiles/directories, advanced certification/event/survey/form/notification/export systems unless required by launch. Legacy duplicate or one-off routes are removed or redirected into canonical page families during route inventory. | Classifying by surface first gives route inventory a clear working rule without prematurely deciding every individual route before the actual route scan. | 2026-05-07T13:37:50.795Z |
| SURF-OWNER-DEC-005 | Maturity assessment versus general survey system | approved_direction | Current maturity assessment stays in V1 as a bounded special assessment flow and the first reusable maturity-assessment pattern. Future maturity assessments for other areas should reuse this pattern. A broader standard survey/form engine is still needed but remains a separate capability/spec. | 2026-05-07T13:54:48.203Z |
acceptance criteria
- Each V1 surface has named actors, purpose, route families, page families, data sources, required patterns, exclusions, and acceptance checks.
- Surface boundaries align with current design, publishing, data, entitlement, and company-workspace specs.
- Page-template-spec can be produced from this artifact without resolving major surface ownership questions.
- Implementation agents can tell whether a route belongs to public, auth/account, admin, publishing/studio, member, vendor, or company workspace.
- All P0 public/private exposure decisions are explicit, especially vendor public profiles versus private practitioner company workspaces.
qa release readiness
summary
Release readiness gates for route conformance, design-system conformance, permission boundaries, publishing safety, responsive/browser smoke, data/migration safety, and final release acceptance.
version
1
artifact id
b523c55c-a22a-4ba6-94c0-d306656e57f7
artifact type
qa-release-readiness-spec
blocks build until plan review
true
hard stops before build
- Do not start rebuild implementation until surface specs, page-template-spec, core data/entitlement specs, and implementation plan are reviewed.
- Do not build public practitioner company profiles or a public practitioner company directory in V1.
- Do not let vendor/company/member client state grant access or publish public records.
- Do not preserve page-specific CSS for shared controls, cards, forms, filters, nav, tables, or page headers.
- Do not let Sanity, Supabase, and HubSpot own the same operational record without a documented source-of-truth boundary.
page template spec artifact
status
draft
version
1
artifact id
427c04a9-40b7-4e55-a642-65b2aee20b2b
family count
26
generated at
2026-05-07T14:36:17.481Z
artifact type
page-template-spec
survey system spec artifact
status
draft
version
1
artifact id
823d14d7-5992-42f3-a2f4-f4738a045f7c
generated at
2026-05-07T15:32:18.075Z
artifact type
survey-system-spec
route family inventory artifact
status
draft
version
1
artifact id
2cec821e-07ba-4aca-81fb-078f163adf44
route count
97
generated at
2026-05-07T13:44:29.161Z
artifact type
route-family-inventory
by disposition
defer
4
v1 keep
90
redirect
3
by target surface
b2bea admin
11
public site
70
auth account
8
member portal
7
vendor portal
1
route family inventory needed before plan
| id | need | blocks | source | status | resolution |
|---|---|---|---|---|---|
| RFI-001 | Map every existing current-site route to one page family in this artifact or to an explicitly approved exception. | page-template-spec and implementation plan | research.current_files and current route scan | completed_draft | Draft route-family-inventory v1 generated from b2bea-website Git tree: 97 routes, 90 v1_keep, 4 defer, 3 redirect. |
| RFI-002 | Mark which blog/resource/custom pages remain intentional design exceptions versus normalize to B2BEA design-system page families. | visual QA baseline and migration scope | design-system-spec open questions | partially_resolved | Decision 1 approved: custom allowed for home, major campaign/resource landing pages, approved custom HTML imports, and signature editorial features; all reusable/index/operational/authenticated surfaces normalize to the B2BEA design system. Exact route tagging still required in route inventory. |
| RFI-003 | Confirm final route prefixes for private company workspace and vendor portal. | route guard and nav implementation | company-workspace-data-spec and entitlement-model-spec | resolved | Decision 2 approved: canonical private route prefixes are /vendor for vendor portal and /company for private practitioner company workspace. |
| RFI-004 | Confirm whether admin and publishing Studio stay separate surfaces or collapse under one admin shell with Studio module nav. | admin IA and shell spec | publishing-model-spec and current /admin /studio layouts | resolved | Decision 3 approved: one authenticated /admin shell; Studio/publishing becomes an admin module, with current /studio routes treated as migration/redirect candidates. |