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

docs: final documentation consolidation - one canonical doc set

Browse Source 
Audited every *.md in docs/ and root. Merged five overlapping backend
docs (BACKEND_INTEGRATION.md + AUTHENTICATION.md + ERROR_CONTRACT.md +
MAINTENANCE_MODE.md + the already-archived BACKEND_API.md/
BACKEND_API_REMAINING_WORK.md) into one canonical docs/BACKEND.md
(4775 lines, 10 numbered sections) - deleted the four standalone
files outright now that their content is fully inlined.

Archived (not deleted - real historical value): ADMIN.md (Sprint
19-28 build log, sprint-report-shaped, not a living reference) and
FRONTEND-ROADMAP.md (despite its name, a shipped-history changelog
with detail no other doc has - not a forward roadmap, so keeping it
in root alongside NEXT_PHASE.md was exactly the "10 roadmaps"
confusion being cleaned up).

Deleted outright (zero value): SPRINTS.md - a leftover copy-pasted
sprint-kickoff prompt saved as a file, not documentation.

Rewrote docs/PROJECT_STATUS.md with completion-percentage estimates
per area (frontend/backend/UI/admin/storefront) and an explicit
first-customer-readiness call. Rewrote docs/NEXT_PHASE.md to the
strict 5-phase structure (backend integration -> production testing
-> performance -> monitoring -> v2 ideas), pointing to PRODUCT_BACKLOG
.md/FUTURE_FEATURES.md for phase 5 detail instead of duplicating it.

Rewrote root README.md - was stale (referenced deleted pages/info,
pages/legal folders from a prior RC pass), now covers architecture,
frontend/backend status, how to run, mock<->API switch mechanism
(useMockData in environment.ts), current folder structure, and a
documentation map.

Updated docs/PROJECT_INDEX.md (the stated entry point) to link only
the surviving doc set - every remaining document is reachable from it.

Fixed every broken/stale cross-reference to the deleted/renamed
backend docs across ARCHITECTURE.md, EDITOR.md, FRONTEND.md,
PROJECT-STRUCTURE.md, StaticPages.md, KNOWN-ISSUES.md (10 individual
link fixes, verified by repo-wide grep before and after). Left
CHANGELOG.md's two historical entries untouched - changelogs are
append-only history, not live navigation, editing past entries would
misrepresent what was true at the time.

Not touched (explicitly out of scope): docs/architecture/foundation/**
(enforced ADRs/governance, permanent not sprint-shaped),
docs/context/** (Barry Cache infrastructure, "do not edit by hand"
per CLAUDE.md), .claude/worktrees/** (separate git worktrees
containing an unrelated project's docs, not this repo's documentation).

docs/ root: 22 files -> 16. Plus 5 in docs/archive/ (was 3).
This commit is contained in:
sdarbinyan
2026-07-26 14:56:25 +04:00
parent d03ef2db50
commit 261ce6d55b
17 changed files with 536 additions and 2075 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/NEXT_PHASE.md
View File

@@ -1,39 +1,23 @@
# Next Phase — Post-Backend-Integration Work
# Next Phase — Roadmap
Everything here assumes a real backend implementing `docs/BACKEND_INTEGRATION.md` exists. None of this can start before that. Not a re-statement of the backend checklist itself (`BACKEND_INTEGRATION.md` §9 owns that) — this is what the frontend needs to do once a real API is reachable.
The one roadmap. Everything after this point assumes the previous phase is done — don't start Phase 2 work before Phase 1 lands.
## Connect gateways
## Phase 1 — Backend integration
Swap every mock gateway for a real one behind its existing (or newly-added) DI token, per the migration checklist in `BACKEND_INTEGRATION.md` §8. Order matters — follow §8's dependency-ordered sequence (auth/tenant/bootstrap first, then read-heavy catalog domains, then write-heavy customer domains, then admin domains, then builder/CMS).
Implement the backend per `BACKEND.md`, then swap every frontend mock gateway for a real one behind its DI token, in the dependency order `BACKEND.md` §8 specifies (auth/tenant/bootstrap first, then read-heavy catalog, then write-heavy customer domains, then admin, then builder/CMS). Wire the currently-dormant Ed25519 admin-auth interceptor/guard once the backend can issue/verify challenges. Enforce the admin role model in route guards once real roles exist server-side.
## Remove mocks
## Phase 2 — Production testing
Once every domain has a real gateway bound and verified, retire the `*LocalGateway`/mock repository implementations (or gate them behind an explicit dev-only flag if they're still useful for offline frontend development). Remove `useMockData`/mock-interceptor paths that are no longer reachable.
Add the automated test suite that doesn't exist yet: facade-level integration tests against real endpoints (not mocks), and E2E coverage for the critical flows — storefront checkout, admin product/category CRUD, builder draft → publish → live storefront reflects the change, admin auth once Ed25519 is live.
## Wire dormant auth
## Phase 3 — Performance
Register the Ed25519 `authInterceptor` in `app.config.ts` and attach `ed25519AuthGuard` to admin routes once a real backend can issue/verify challenges — currently fully built but not activated. Fix the `toAuthErrorShape()` gap noted in `KNOWN-ISSUES.md` so `session-expired`/`invalid-signature` screens become reachable once the backend returns a body-level error code.
Re-profile under real backend latency (mock responses are instant today, real ones won't be) — loading states, skeleton timing. Revisit the two known large lazy chunks (`project-editor`, `catalog-container`) with real data before committing to a bundle-splitting approach.
## Enforce the role model
## Phase 4 — Monitoring
Wire the existing (currently unenforced) `AdminRole` model into route guards and UI gates — right now anyone who passes admin auth has full access regardless of role.
Wire real error tracking/APM and a real event source for the admin Monitoring page (currently mock activity data). Implement the maintenance-mode frontend UI gaps `BACKEND.md` §10 flags as not existing yet (full-page takeover, per-module banners, scheduled-maintenance countdown), once the backend maintenance contract is live.
## Integration testing
## Phase 5 — Version 2 ideas
No automated test suite exists yet for any of the touched areas. Once real endpoints exist, this is the point to add integration tests against them (not against mocks) — facade-level tests verifying real request/response shapes match `BACKEND_INTEGRATION.md`.
## E2E tests
Critical flows worth covering first: storefront checkout (cart → order → payment), admin product/category CRUD, builder draft → publish → live storefront reflects the change, admin auth (once Ed25519 is live).
## Performance profiling
Real backend latency will differ from the instant mock responses today — re-profile loading states, skeleton timing, and the two known large lazy chunks (`project-editor`, `catalog-container`) under real network conditions before committing to a bundle-splitting approach.
## Production monitoring
Wire real error tracking/APM once real endpoints exist — the current admin Monitoring page is mock activity data with no real event source. Decide on the actual monitoring/observability stack as part of backend infra (out of frontend scope, but the frontend's Monitoring UI is ready to display real events once real events exist — see `BACKEND_INTEGRATION.md` §3 Monitoring).
## Maintenance mode
Build the frontend UI gaps explicitly flagged as not existing yet in `docs/MAINTENANCE_MODE.md` (full-page maintenance takeover, per-module inline banners, scheduled-maintenance countdown) once the backend maintenance-mode contract (also in that doc) is decided and implemented.
Everything in `docs/PRODUCT_BACKLOG.md` (dark mode, brand-color contrast decision, advanced analytics, additional payment providers, Contacts page content) and `docs/FUTURE_FEATURES.md` (Angular 22 upgrade, cart-modal composition cleanup) — none of it scheduled, all of it deliberately deferred past initial launch.