Files

sdarbinyan 5374401257 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

5.0 KiB

Raw Blame History

Storefront Review — RC STORE-01

Archived, correction (2026-07-25): the category/search skeleton fix below was applied to pages/category/*/pages/search/*, which turned out to be unrouted dead code — see docs/KNOWN-ISSUES.md item 13. The fix itself is harmless but has zero production effect. Kept here for historical accuracy.

Mission: polish the customer-facing storefront only (Home, Catalog, Search, Product, Compare, Wishlist, Cart, Checkout, Static Pages). No redesign, no architecture change, no Builder/Backoffice changes. Reused existing src/app/shared/ui/* components exclusively.

This is the third storefront-focused pass, on top of two prior sprints already documented:

Doc	Scope
`docs/UI-COMPOSITION-REVIEW.md` (RC-Visual-02)	Composition bugs: undefined theme vars, hand-rolled skeletons/empty-states → shared components, missing `scope="col"`, dead CSS.
`docs/STORE_FRONT_UX_REVIEW.md` (RC-Premium-01)	Visual/interaction polish: typography, spacing, hover/focus/active states, color-only-signal fixes (aria-pressed/current/live), transitions, badges/price/discount presentation.
This doc (RC STORE-01)	Closed the concrete gaps those two passes deliberately deferred, re-verified nothing regressed.

What this pass found

Re-checked docs/KNOWN-ISSUES.md items 6-10 (all flagged during RC-Premium-01, 2026-07-23) against the current tree before doing any new inspection — per this mission's "don't rediscover" instruction, existing docs were the source of truth, not a fresh repo-wide audit.

Of the 5 flagged items, 2 were safe, scoped, non-architectural fixes matching this mission's focus list (Skeletons, and general cleanup); 3 require an architecture or design-system decision and were correctly left alone both times.

Fixed this pass

Category/Search skeleton → shared app-skeleton. src/app/pages/category/* and src/app/pages/search/* still had their own .skeleton-card/.skeleton-image/.skeleton-line markup with a hardcoded-hex shimmer animation, duplicating exactly what app-skeleton (already used by catalog-container and product-details-container) provides. Swapped both pages to app-skeleton (shape="rect" for image/button, shape="text" for lines), deleted the now-dead per-page shimmer CSS (~50 lines/page, hardcoded hex removed). Structural wrapper classes (.item-card, .item-details) kept for grid layout — only the shimmer implementation moved to the shared primitive. Commit: 2e85495.
Cart: removed dead .email-form markup + CSS. Post-payment email/phone-capture form was commented-out HTML (cart.component.html) with a live ~90-line .email-form/.email-input/.submit-email-btn CSS block still shipping in the bundle for markup that never renders. Removed both. No .ts logic touched — the component's email/phone handler methods still exist and are unaffected; if they're confirmed unused elsewhere, that's a separate dead-code decision, not in scope here. Commit: ce96ef1.

Deliberately not touched (architecture/design decisions, not polish)

Payment modal / bank-payment iframe on Cart — still a custom component, not app-dialog. It owns a real multi-step state machine and its own focus-trap already; migrating it is a composition change. Flagged three times now (RC-Visual-02, RC-Premium-01, this pass) — recommend a dedicated ticket rather than deferring again silently.
Cart's clearCart() native confirm() — no existing storefront confirm-dialog pattern to follow; introducing the first one is an architecture decision (which shared dialog variant, where it lives), not a polish-pass call.
stars.component rating glyph color + legacy hex in category/search — no exact token match in the current palette. Needs a deliberate token-extension decision (add a token vs. accept the literal) before touching, to avoid guessing at a visual outcome nobody signed off on.

Verification

tsc --noEmit: clean.
npm run build: green, only the pre-existing bundle-budget warning (768 kB vs 700 kB, unrelated to this pass).
Manual: category/search skeleton markup swap is a like-for-like structural replacement (same wrapper classes, same grid), verified by reading rendered template output; no visual-regression risk beyond the shimmer implementation itself, which is the same shimmer app-skeleton already renders elsewhere in the same app.
No live browser session available this session; recommend a quick visual check of category/search infinite-scroll loading state and the cart post-payment success screen before shipping.

Storefront status after this pass

Home, Catalog, Search, Product, Compare, Wishlist, Cart, Checkout (payment section within Cart — no separate checkout route), Static Pages: all three passes (composition, visual polish, this cleanup) complete. Remaining open items are the 3 above, all correctly gated behind a decision outside a pure polish/cleanup pass's scope — not silently dropped, tracked in docs/KNOWN-ISSUES.md (items 6-8) and docs/FRONTEND-ROADMAP.md.

5.0 KiB Raw Blame History