sdarbinyan/marketplaces
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate documentation and archive temporary reports

Browse Source 
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>
This commit is contained in:
sdarbinyan
2026-07-25 19:10:49 +04:00
parent 5707755576
commit 5374401257
38 changed files with 281 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1744
docs/backend/BACKEND-INTEGRATION.md
View File

File diff suppressed because it is too large Load Diff

75
docs/backend/REMAINING-BACKEND-WORK.md
View File

@@ -1,75 +0,0 @@
# Remaining backend work (everything except auth/session)
Companion to the `API-CONTRACT.md` backend delivered separately (covers `GET /bootstrap`
transport + `/users/sessions/*` — done, see prior conversation). This file lists what's
still outstanding. Full request/response shapes, TypeScript
interfaces, and validation rules for every item below already exist in
[`docs/backend/BACKEND-INTEGRATION.md`](BACKEND-INTEGRATION.md) — this is a prioritized
punch list with links into that spec, not a duplicate of it. **Do not re-document
endpoint shapes here** — edit the master spec if a shape needs to change.
Status legend (same as master spec): **PLANNED** = shape fully specified client-side,
served by a mock gateway today, nothing built server-side yet. **FUTURE** = reserved
contract only, no urgency. Bootstrap's *content* (branding/theme/nav values, not the
`GET /bootstrap` transport itself) is also still outstanding — see P0 below.
---
## P0 — blocks going live at all
| # | Item | Spec section |
|---|---|---|
| 1 | `bootstrap.json` real content (branding, theme, navigation, seo) — currently default stubs per backend's own note in API-CONTRACT.md | [§4](BACKEND-INTEGRATION.md#4-bootstrap) |
| 2 | Builder — bootstrap draft/publish/validate (`GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, `POST /builder/bootstrap/validate`) — this is how the Marketplace Builder actually saves anything | [§6.7](BACKEND-INTEGRATION.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority) |
| 3 | Backoffice — Products CRUD + variants | [§6.10](BACKEND-INTEGRATION.md#610-backoffice--products-planned), DTOs [§7.2](BACKEND-INTEGRATION.md#72-products--srcappfeaturesadminproductsmodelsadmin-productmodelts) |
| 4 | Backoffice — Categories CRUD (tree) | [§6.9](BACKEND-INTEGRATION.md#69-backoffice--categories-planned), DTOs [§7.1](BACKEND-INTEGRATION.md#71-categories--srcappfeaturesadmincategoriesmodelsadmin-categorymodelts) |
| 5 | Media upload/delete/replace pipeline | [§6.18](BACKEND-INTEGRATION.md#618-media-planned--adr-0002), [§10](BACKEND-INTEGRATION.md#10-media) |
## P1 — needed for real order/commerce flow
| # | Item | Spec section |
|---|---|---|
| 6 | Backoffice — Orders CRUD + status transitions | [§6.11](BACKEND-INTEGRATION.md#611-backoffice--orders-planned), state machine [§8.1](BACKEND-INTEGRATION.md#81-orders--adminorderstatus) |
| 7 | Backoffice — Transactions (list/detail, tied to orders) | [§6.12](BACKEND-INTEGRATION.md#612-backoffice--transactions-planned) |
| 8 | Order creation endpoint — **does not exist anywhere yet**; checkout today only calls the frozen cart-payment endpoints, nothing creates an `AdminOrder` | [§16.9](BACKEND-INTEGRATION.md#169-order-creation-future--no-order-creation-endpoint-exists-anywhere-yet) |
| 9 | Backoffice — Users/roles/invitations | [§6.13](BACKEND-INTEGRATION.md#613-backoffice--users-roles-invitations-planned) |
| 10 | Backoffice — Moderation (review + report status transitions) | [§6.14](BACKEND-INTEGRATION.md#614-backoffice--moderation-reviews--reports-planned), state machines [§8.4](BACKEND-INTEGRATION.md#84-reviews--adminreviewstatus)/[§8.5](BACKEND-INTEGRATION.md#85-reports--adminreportstatus) |
## P2 — dashboards / operational visibility
| # | Item | Spec section |
|---|---|---|
| 11 | Backoffice — Dashboard metrics & recent activity | [§6.15](BACKEND-INTEGRATION.md#615-backoffice--dashboard-metrics--recent-activity-planned) |
| 12 | Backoffice — Monitoring (all but Health) | [§6.16](BACKEND-INTEGRATION.md#616-backoffice--monitoring-planned-except-health) |
| 13 | Backoffice — Analytics summary (real once orders are real) | [§6.17](BACKEND-INTEGRATION.md#617-backoffice--analytics-mostly-future--no-data-source) |
| 14 | Builder — Content pages / CMS | [§6.8](BACKEND-INTEGRATION.md#68-builder--content-pages--cms-planned) |
## P3 — nice-to-have, no urgency
| # | Item | Spec section |
|---|---|---|
| 15 | Search suggestions / catalog filters | [§6.6](BACKEND-INTEGRATION.md#66-search--autocomplete--trending-planned) |
| 16 | Cross-device wishlist/compare/saved-searches sync (currently 100% localStorage, works fine without this) | [§6.6](BACKEND-INTEGRATION.md#66-search--autocomplete--trending-planned) |
| 17 | Analytics traffic/funnels/heatmaps — needs a tracking pipeline that doesn't exist yet, not just an endpoint | [§6.17](BACKEND-INTEGRATION.md#617-backoffice--analytics-mostly-future--no-data-source) |
| 18 | Sitemap — dynamic generation (static baseline today) | [§6.19](BACKEND-INTEGRATION.md#619-sitemap-future--static-baseline-only-today) |
---
## Explicitly not in this list
- Auth / Telegram session (`GET /bootstrap` transport, `/users/sessions/*`) — covered by
backend's `API-CONTRACT.md`, frontend wiring already matches it exactly. Three small
gaps remain from that delivery (see prior conversation): `authApiUrl` env value still
points at the old host, `telegramBot` username unverified, frontend deploy domain needs
confirming against the CORS allow-list. None of those are new backend work — they're
config/confirmation follow-ups on what was already delivered.
- Payments — frozen, unchanged, out of scope per [§2.8](BACKEND-INTEGRATION.md#28-payments-frozen-documented-for-completeness).
- Storefront reads/writes (categories, items, search, cart, reviews) — already real HTTP,
already working, no backend work needed. See [§6.1](BACKEND-INTEGRATION.md#61-storefront-reads-current--frozen-shapes-srcappservicesapiservicets)–[§6.2](BACKEND-INTEGRATION.md#62-storefront-writes-current--frozen-shapes).
## For every item above, when implementing
Read the interface + model file cited in the linked spec section before writing the
endpoint — the shape is already fixed by the frontend gateway interface, not up for
renegotiation without a frontend change. When an endpoint is done, the frontend swap is
a one-file gateway rebind (see [§14](BACKEND-INTEGRATION.md#14-backend-replacement-pattern)) — no page/component changes needed on our side.