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](KNOWN-ISSUES.md) item 13, tracked in [TODO.md](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](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`](../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](BACKEND_API.md) for the full CURRENT/PLANNED/FUTURE endpoint spec, [BACKEND_API_REMAINING_WORK.md](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](ARCHITECTURE.md) | Layered architecture, container/facade/service pattern, bootstrap/theme/widget engines, links to the enforced ADRs |
| [BACKEND_API.md](BACKEND_API.md) | Canonical backend/API spec — every endpoint, DTO, state machine, error contract |
| [BACKEND_API_REMAINING_WORK.md](BACKEND_API_REMAINING_WORK.md) | Prioritized backend punch list (companion to the spec above) |
| [FRONTEND.md](FRONTEND.md) | App structure, routing, i18n, theming, state management, dynamic rendering |
| [EDITOR.md](EDITOR.md) | The Project Editor: every section, save/publish/draft/reset model |
| [StaticPages.md](StaticPages.md) | The Static Pages CMS module (the thing that actually serves About/Contacts/etc. today) |
| [PROJECT-STRUCTURE.md](PROJECT-STRUCTURE.md) | Folder-by-folder tour of `src/app/**` with a worked feature-add example |
| [ADMIN.md](ADMIN.md) | Admin backoffice: routing, architecture, data sources |
| [AUTH.md](AUTH.md) | Ed25519 admin auth — prepared, not live; current live gate is Telegram-QR |
| [FRONTEND-ROADMAP.md](FRONTEND-ROADMAP.md) | Status snapshot refreshed from recent commits — what shipped, what's open |
| [KNOWN-ISSUES.md](KNOWN-ISSUES.md) | Running list of open/fixed bugs found during manual verification |
| [TODO.md](TODO.md) | Checklist of everything still remaining, verified against current repo state |
| [ANGULAR22_PLAN.md](ANGULAR22_PLAN.md) | Angular 22 upgrade feasibility (research only, not yet executed) |
| [SALES-GUIDE.md](SALES-GUIDE.md) | Plain-language guide for the sales team — what to demo, what's not live yet |
| [`../DESIGN.md`](../DESIGN.md) | Visual design system: colors, typography, elevation, component specs |
| [`../PRODUCT.md`](../PRODUCT.md) | Product positioning, users, brand personality, anti-references |
| [`../CHANGELOG.md`](../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](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](KNOWN-ISSUES.md)/[FRONTEND-ROADMAP.md](FRONTEND-ROADMAP.md)/[TODO.md](TODO.md). Full original text recoverable via `git log --diff-filter=D -- docs/archive` if needed.

## How to run it

```bash
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):

```bash
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](FRONTEND-ROADMAP.md) for the summary of each.
- **Angular 22 upgrade**: not started, feasibility researched — see [ANGULAR22_PLAN.md](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](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](BACKEND_API.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority).