marketplaces/docs/PROJECT.md

Marketplace Platform

Read First

• DESIGN.md — does not exist under this name; closest equivalent is ARCHITECTURE.md (system design) + docs/architecture/foundation/** (enforced standards/ADRs).
• BACKEND-API.md — does not exist under this name; canonical spec is backend/BACKEND-INTEGRATION.md.
• ADMIN.md
• EDITOR.md
• KNOWN-ISSUES.md
• FRONTEND-ROADMAP.md
• ADR/ — docs/architecture/foundation/adr/ (ADR-001…ADR-010) and docs/context/adrs/.

What this is

A configuration-driven, multi-tenant SaaS marketplace platform (Angular 18+, standalone components). One frontend codebase serves unlimited tenants ("marketplaces"). Tenant identity, theme, navigation, page/section/widget composition, and static content are all resolved from a per-tenant bootstrap.json fetched at runtime — no tenant-specific code paths exist in the frontend. See docs/ARCHITECTURE.md and docs/backend/BACKEND-INTEGRATION.md#4-bootstrap for the mechanics.

Every tenant conceptually has three surfaces on this one codebase:

• Website — the public storefront (catalog, product pages, cart, static pages).
• Builder (Project Editor) — an in-app editor that edits the tenant's BootstrapConfig (see docs/EDITOR.md).
• Backoffice (Admin) — an admin area for products, and (as of Sprint 19) a dashboard; more domains are placeholders pending backend (see docs/ADMIN.md).

Tenant / marketplace model

• Tenant is resolved only by request domain/host — never by query param, localStorage, or hardcoded ID.
• The frontend loads GET /bootstrap (tenant resolved server-side by host) and renders entirely from that JSON: theme, layout, navigation, pages, sections, widgets, static pages, feature flags.
• Widgets never call APIs directly; they receive resolved data through facades/resolvers.
• New tenants are onboarded by domain + bootstrap config + backend data, not by forking the frontend.
• Full contract: docs/backend/BACKEND-INTEGRATION.md#4-bootstrap.

Doc index

• ARCHITECTURE.md — layered architecture, container/facade/service pattern, bootstrap/theme/widget engines, links to the enforced ADRs.
• backend/BACKEND-INTEGRATION.md — the single canonical backend/API spec: architecture, auth, security, bootstrap, conventions, every endpoint (CURRENT/PLANNED/FUTURE), DTOs, state machines, validation, media, errors, localization, caching. Start here if you're a backend engineer picking up this project.
• FRONTEND.md — app structure, routing, i18n, theming, state management (signals/facades, no NgRx), dynamic rendering.
• EDITOR.md — the Project Editor: every section, the save/publish/draft/reset model, and the field-description/dropdown UX.
• StaticPages.md — the Static Pages module: full field reference, per-page draft/publish gating, CRUD/search/filter/bulk, rich text, device preview, nav integration (Sprint X+2).
• PROJECT-STRUCTURE.md — folder-by-folder tour of src/app/** with a worked "add a new feature" example (admin dashboard).
• ADMIN.md — Sprint 19 admin dashboard: routing, architecture, data sources, known gaps.
• FRONTEND-ROADMAP.md — status snapshot refreshed from recent commits; sprint progress, known open items.
• KNOWN-ISSUES.md — running list of open/fixed bugs found during manual verification.
• PERFORMANCE_REPORT.md — RC PERF-01: bundle/reactivity/asset audit and fixes.
• ACCESSIBILITY_REPORT.md — RC A11Y-01: WCAG 2.1 AA audit and fixes across all 3 surfaces.
• RELEASE_REPORT.md — live browser release-candidate walkthrough, P0/P1 findings and fixes.
• docs/architecture/foundation/** — the enforced ADRs (ADR-001…ADR-010) and standards docs (Coding-Standards, Naming-Conventions, Dependency-Rules, Folder-Blueprint, Import-Boundary-Matrix, State-Management-Standards, Configuration-Standards, Component-Standards, Service-Standards). These are governance, not narrative — read them directly; ARCHITECTURE.md only links to them.
• docs/context/** — Barry Cache's own source-backed memory system. Infrastructure, not project documentation; do not edit by hand.

How to run it

From package.json:

npm install
npm run start          # ng serve
npm run start:dexar     # ng serve --configuration=development --port 4200
npm run build           # ng build
npm run build:dexar     # ng build --configuration=production
npm run watch           # ng build --watch --configuration development
npm run arch:check      # boundary + circular-dependency checks (tools/architecture/check-boundaries.mjs, madge)

Barry Cache (repo memory, optional but recommended before/after non-trivial work):

npm run barry -- resume --task "<task>"
npm run barry -- validate

See root CLAUDE.md for the full Barry Cache workflow and memory policy.

Current Status

• Frontend: 96%
• Backend: in progress — still mostly PLANNED/mock gateways, no confirmed live backend contract (see docs/backend/BACKEND-INTEGRATION.md)
• Storefront polish: done (RC-Visual-02, RC-Premium-01, RC STORE-01)
• Performance audit: done — see PERFORMANCE_REPORT.md (initial bundle −24%)
• Angular v22: pending
• Accessibility audit: done — see ACCESSIBILITY_REPORT.md (WCAG 2.1 AA, storefront/builder/backoffice)
• Release-candidate walkthrough: done — see RELEASE_REPORT.md (2 P0s + 6 P1s found and fixed via live browser walkthrough)
• First client demo: upcoming

Detail behind each line: sprint-by-sprint history in FRONTEND-ROADMAP.md / docs/SPRINT-PLAN.md (Sprints 20-30, all shipped except Sprint 30's git push, pending explicit go-ahead), open defects in KNOWN-ISSUES.md, backend gap list in docs/backend/BACKEND-INTEGRATION.md and docs/backend/REMAINING-BACKEND-WORK.md.

Draft/publish for the Project Editor is still frontend-only (localStorage), with no backend persistence — the single largest backend gap, see docs/backend/BACKEND-INTEGRATION.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority.

This documentation set (docs/PROJECT.md, ARCHITECTURE.md, backend/BACKEND-INTEGRATION.md, FRONTEND.md, EDITOR.md, PROJECT-STRUCTURE.md) replaces ~35 previously scattered files under docs/platform/, docs/backend-platform/, and various one-off sprint reports, which have been consolidated and removed.