docs: consolidate scattered docs into canonical set
Replace ~35 organically-grown docs (docs/platform/*, docs/backend-platform/*, one-off sprint reports, Search.md, Diagnostics.md, Content-Management.md, Backend-Handoff-Sprint16.md, docs/superpowers/*, docs/Project-Editor.md, untracked docs/total.md) with the six canonical docs declared in .claude/CLAUDE.md: PROJECT.md, ARCHITECTURE.md, BACKEND.md, FRONTEND.md, BOOTSTRAP.md, EDITOR.md, plus a new PROJECT-STRUCTURE.md. - BACKEND.md is a punch list per domain (auth, bootstrap draft/publish, static pages, categories, products, orders, dashboard metrics, activity, translations, search, product engagement) plus a Known reliability issues section on the prod 502/504 root cause. - ARCHITECTURE.md links to (does not duplicate) the enforced docs/architecture/foundation/** ADRs and standards docs. - docs/ADMIN.md and docs/architecture/foundation/** and docs/context/** are left untouched per instructions. - Updated the one dangling docs/Project-Editor.md reference in admin-auth.service.ts to point at docs/BACKEND.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
60
docs/PROJECT.md
Normal file
60
docs/PROJECT.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# PROJECT
|
||||
|
||||
## 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/BOOTSTRAP.md` 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/BOOTSTRAP.md`.
|
||||
|
||||
## Doc index
|
||||
|
||||
- **[ARCHITECTURE.md](ARCHITECTURE.md)** — layered architecture, container/facade/service pattern, bootstrap/theme/widget engines, links to the enforced ADRs.
|
||||
- **[BACKEND.md](BACKEND.md)** — the backend punch list: every mocked/local-only feature, its gap, and the endpoint needed to make it real. Start here if you're a backend engineer picking up this project.
|
||||
- **[FRONTEND.md](FRONTEND.md)** — app structure, routing, i18n, theming, state management (signals/facades, no NgRx), dynamic rendering.
|
||||
- **[BOOTSTRAP.md](BOOTSTRAP.md)** — the `BootstrapConfig` model, field-by-field, with a representative example JSON.
|
||||
- **[EDITOR.md](EDITOR.md)** — the Project Editor: every section, the save/publish/draft/reset model, and the field-description/dropdown UX.
|
||||
- **[PROJECT-STRUCTURE.md](PROJECT-STRUCTURE.md)** — folder-by-folder tour of `src/app/**` with a worked "add a new feature" example (admin dashboard).
|
||||
- **[ADMIN.md](ADMIN.md)** — Sprint 19 admin dashboard: routing, architecture, data sources, known gaps.
|
||||
- `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`:
|
||||
|
||||
```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 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):
|
||||
|
||||
```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 (this sprint)
|
||||
|
||||
- **Sprint 19** shipped the production Admin Dashboard (`src/app/features/admin/dashboard/`) as the default `/:lang/backoffice` landing page, wired the previously-unrouted `admin/products` feature into routing, and added `lastPublishedAt` tracking to `ProjectEditorFacade`. See `docs/ADMIN.md`.
|
||||
- **Sprint 18** added Project Editor autosave (localStorage draft), section/draft reset, admin QR-login reuse (shared Telegram session API/component, separate cookie/guard), and Ed25519 verification scaffolding (no crypto implemented yet — fails closed). See `docs/EDITOR.md`.
|
||||
- Draft/publish for the Project Editor is still **frontend-only** (localStorage), with no backend persistence. This is the single largest backend gap — see `docs/BACKEND.md`.
|
||||
- This documentation set (`docs/PROJECT.md`, `ARCHITECTURE.md`, `BACKEND.md`, `FRONTEND.md`, `BOOTSTRAP.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.
|
||||
Reference in New Issue
Block a user