marketplaces/docs/PROJECT_INDEX.md

Marketplace Platform — Documentation Index

This is the entry point. Read this first — it links to everything else and tells you what's actually true right now versus what's historical.

⚠️ Read before touching routing or storefront static pages

pages/category/*, pages/search/*, pages/item-detail/*, pages/info/**, and pages/legal/** (40+ files) look like live storefront pages but are entirely unrouted dead code. src/app/app.routes.ts's cmsContentRoutes is a literal empty array. The real routes redirect category/:id/search to CatalogContainerComponent, product/:id to ProductDetailsContainerComponent, and every static/legal page (About, Contacts, FAQ, etc.) is served by the catch-all :staticPath route resolving bootstrap.staticPages — not by the hardcoded components under pages/info/pages/legal. Full detail: KNOWN-ISSUES.md item 13. Several polish passes in docs/archive/ were applied to this dead code before this was caught — treat any claim in an archived doc about "the category page" or "the search page" as not describing what currently renders in production.

What this is

A configuration-driven, multi-tenant SaaS marketplace platform (Angular 21.1, standalone components). One frontend codebase serves unlimited tenants ("marketplaces"). Tenant identity, theme, navigation, page/section/widget composition, and static content all resolve from a per-tenant bootstrap.json fetched at runtime — no tenant-specific code paths exist in the frontend. New tenants are onboarded by domain + config + backend data, never by forking the frontend.

Every tenant has three surfaces on this one codebase:

• Website — the public storefront (catalog, product pages, cart, static pages).
• Builder (Project Editor, /edit/**) — an in-app editor that edits the tenant's BootstrapConfig.
• Backoffice (Admin, /:lang/backoffice/**) — the admin area: products, categories (live-wired to a real gateway), orders, transactions, users, monitoring, analytics, media.

System overview

• Architecture: Component (container) → Facade → Domain Service → Repository/Provider (DI token, swappable mock↔API) → Mock | API. Enforced by npm run arch:check (import boundaries + circular deps), not just convention. Full detail: ARCHITECTURE.md, governance docs at docs/architecture/foundation/** (10 ADRs + 9 standards docs).
• State: Signals-based facades everywhere, no NgRx (ADR-007).
• Rendering: Bootstrap JSON → Section Engine → Page Renderer → Widget Host → registered widget component (ADR-005). 100% lazy-loaded routes.
• Theming: CSS custom properties per tenant, 3 theme stylesheets, never hardcoded hex in a component (ADR-008). Design system spec: DESIGN.md (root of repo).
• i18n: 3 locales (en/ru/hy), compile-time-enforced key parity across locale files.
• Backend: mostly PLANNED (mock gateways behind swappable provider tokens) — see BACKEND_API.md for the full CURRENT/PLANNED/FUTURE endpoint spec, BACKEND_API_REMAINING_WORK.md for the prioritized punch list. Categories is the one domain fully wired to a real HTTP gateway; everything else is local/mock.

Doc index (living documents)

Read these directly — they're the current source of truth, not one-off reports:

Doc	What it covers
ARCHITECTURE.md	Layered architecture, container/facade/service pattern, bootstrap/theme/widget engines, links to the enforced ADRs
BACKEND_API.md	Canonical backend/API spec — every endpoint, DTO, state machine, error contract
BACKEND_API_REMAINING_WORK.md	Prioritized backend punch list (companion to the spec above)
FRONTEND.md	App structure, routing, i18n, theming, state management, dynamic rendering
EDITOR.md	The Project Editor: every section, save/publish/draft/reset model
StaticPages.md	The Static Pages CMS module (the thing that actually serves About/Contacts/etc. today)
PROJECT-STRUCTURE.md	Folder-by-folder tour of src/app/** with a worked feature-add example
ADMIN.md	Admin backoffice: routing, architecture, data sources
AUTH.md	Ed25519 admin auth — prepared, not live; current live gate is Telegram-QR
FRONTEND-ROADMAP.md	Status snapshot refreshed from recent commits — what shipped, what's open
KNOWN-ISSUES.md	Running list of open/fixed bugs found during manual verification
ANGULAR22_PLAN.md	Angular 22 upgrade feasibility (research only, not yet executed)
SALES-GUIDE.md	Plain-language guide for the sales team — what to demo, what's not live yet
../DESIGN.md	Visual design system: colors, typography, elevation, component specs
../PRODUCT.md	Product positioning, users, brand personality, anti-references
../CHANGELOG.md	Keep-a-Changelog-format history of shipped features
docs/architecture/foundation/**	Enforced ADRs (ADR-001…ADR-010) and standards docs — governance, read directly
docs/context/**	Barry Cache's own source-backed memory system — infrastructure, not project documentation, do not edit by hand

One topic, one place: routing lives in FRONTEND.md, not repeated here. Backend contract lives in BACKEND_API.md, not repeated in ADMIN.md. Design tokens live in DESIGN.md, not repeated in the archived UI review docs. If you find the same fact stated two places with different values, the doc in this table wins over anything in docs/archive/.

Historical / completed audits — docs/archive/

One-time audit reports, sprint reports, and polish-pass logs. Useful for "why was this changed" archaeology, not for "what's true now" — check the living docs above for that. Contents: SPRINT-PLAN.md, ADMIN-UX-AUDIT.md, ADMIN_REVIEW.md, RELEASE-CANDIDATE-AUDIT.md, STORE_FRONT_REVIEW.md, STORE_FRONT_UX_REVIEW.md, STORE_REVIEW.md, UI-COMPOSITION-REVIEW.md, UI-DESIGN-REVIEW.md, UI-ICON-AUDIT.md, PERFORMANCE_REPORT.md, ACCESSIBILITY_REPORT.md, RELEASE_REPORT.md, CLEANUP_REPORT.md, PROJECT-STATE.md, plus 3 early sprint reports and a platform-standardization report at the repo root's docs/archive/. Every open finding worth keeping from these was merged into KNOWN-ISSUES.md or FRONTEND-ROADMAP.md before archiving — nothing was lost, just deduplicated.

How to run it

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 arch:check       # boundary + circular-dependency checks

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% of planned UI built. Storefront/Builder/Backoffice all have working UI; several polish/audit passes complete (see below).
• Backend: in progress — mostly PLANNED/mock gateways, no confirmed live backend contract beyond auth/session and storefront reads. Categories is the one domain fully wired to a real gateway.
• Storefront polish, performance audit, WCAG 2.1 AA accessibility audit, release-candidate walkthrough: all done — see FRONTEND-ROADMAP.md for the summary of each, docs/archive/ for the full original reports.
• Angular 22 upgrade: not started, feasibility researched — see ANGULAR22_PLAN.md (verdict: safe, ~2-3.5 days, 2 tooling blockers to clear first).
• Documentation: consolidated (this pass) — 19 one-off reports archived, 2 files renamed for clarity (PROJECT.md→PROJECT_INDEX.md, backend/BACKEND-INTEGRATION.md→BACKEND_API.md), 1 duplicate deleted (RELEASE-NOTES.md merged into CHANGELOG.md).
• First client demo: upcoming — blocked on nothing documentation can fix; see KNOWN-ISSUES.md for what's still open, starting with the dead-routes finding at the top of this document.

Draft/publish for the Project Editor is still frontend-only (localStorage), no backend persistence — the single largest backend gap, see BACKEND_API.md §6.7.