sdarbinyan/marketplaces
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
53744012578f0390c6976ee1def3cf352e203708
marketplaces/docs/PROJECT_INDEX.md

88 lines
8.6 KiB
Markdown
Raw Normal View History

docs: consolidate documentation and archive temporary reports Step 1-2 (audit + plan): classified 35 project markdown files into Core/Architecture/ADR/Temporary-audit/Sprint-report/Generated-review/ Duplicate/Obsolete/Historical. Agent-tooling files (.agents/skills/**, .superpowers/**, docs/context/**, CLAUDE.md/GEMINI.md/AGENTS.md/ .github/copilot-instructions.md) explicitly out of scope — intentional per-tool duplication, not documentation debt. Step 3 (merge, no information lost): - docs/PROJECT.md -> docs/PROJECT_INDEX.md, rewritten as the single entry point: system overview, living-doc index, archive pointer, current status, and a critical-finding callout up top. - docs/backend/BACKEND-INTEGRATION.md -> docs/BACKEND_API.md, docs/backend/REMAINING-BACKEND-WORK.md -> docs/BACKEND_API_REMAINING_WORK.md (also folded in a legitimate uncommitted status update that had been sitting unstaged all session: categories marked DONE, order-creation endpoint noted done). - RELEASE-NOTES.md merged into CHANGELOG.md (was a near-duplicate of the same release content in friendlier prose), then deleted. - KNOWN-ISSUES.md: added item 13 (see below) and item 14 (missing canDeactivate on admin/products edit, from the archived PROJECT-STATE audit, re-verified still true); added a correction note to Fixed item 7. - All cross-references to renamed/moved files fixed across every kept doc (grep+sed pass, then verified with a link-existence check across all 58 in-scope markdown files -> 0 broken links). Step 4 (archive, nothing deleted without merging first): created docs/archive/, moved 19 files there (3 root sprint reports, 1 platform report, SPRINT-PLAN.md, and 14 one-off audit/review/report docs). Added correction headers to the 3 archived docs whose conclusions were affected by the finding below, rather than silently leaving them misleading. Step 5: docs/PROJECT_INDEX.md rewritten per the mission brief - someone opening the repo should understand the whole system from it. IMPORTANT FINDING (surfaced during this audit, not the mission's primary goal but too significant to bury): pages/category/*, pages/search/*, pages/item-detail/*, pages/info/**, pages/legal/** (40+ files) are entirely unrouted dead code - app.routes.ts's cmsContentRoutes is a literal empty array, and category/search/product routes redirect to CatalogContainerComponent/ ProductDetailsContainerComponent, not these files. Confirmed against app.routes.ts directly and cross-checked against FRONTEND.md's own routing description. This means several fixes from earlier this cycle (RC-Premium-01, RC STORE-01) and the dead-code cleanup sprint's conclusion that these files were live were all wrong - documented as KNOWN-ISSUES.md item 13, flagged at the top of PROJECT_INDEX.md, and noted on the 3 archived docs whose conclusions it affects. No application code was changed to fix this (out of scope per this session's 'documentation only' constraint) - it needs a wire-it-up-or- delete-it decision first. Verification: tsc --noEmit clean, npm run build green, all markdown links across 58 in-scope files resolve (checked programmatically). No application/Angular/backend code modified. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-25 19:10:49 +04:00
# 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. 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](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 |
| [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 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](KNOWN-ISSUES.md) or [FRONTEND-ROADMAP.md](FRONTEND-ROADMAP.md) before archiving — nothing was lost, just deduplicated.
## 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, `docs/archive/` for the full original reports.
- **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).
Reference in New Issue Copy Permalink