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, tracked in TODO.md. Several earlier polish passes (see git history) were applied to this dead code before this was caught.

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
TODO.md	Checklist of everything still remaining, verified against current repo state
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 elsewhere.

What's still open

TODO.md — checklist of every remaining item across the docs, verified against current repo state.

Historical reports

19 one-off audit/sprint/review reports were archived, then deleted once every open finding worth keeping was confirmed merged into KNOWN-ISSUES.md/FRONTEND-ROADMAP.md/TODO.md. Full original text recoverable via git log --diff-filter=D -- docs/archive if needed.

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.
• 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.