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

4.9 KiB

Raw Blame History

FRONTEND

Angular 18+, standalone components throughout (no NgModules). See docs/PROJECT-STRUCTURE.md for the full src/app/** folder tour and docs/ARCHITECTURE.md for the layered container/facade/service pattern.

App structure at a glance

src/app/
  core/          domain services, DTOs, mappers, repositories (per domain: categories, products, search, admin-auth)
  facades/       cross-feature facades (platform/category.facade.ts, platform/search.facade.ts, ...)
  features/      feature modules (project-editor, admin/*, backoffice/*, website/catalog, website/product, diagnostics, content-management, search)
  shared/        models/config (BootstrapConfig + ~20 sub-configs), shared UI, utils — feature-agnostic
  widgets/       widget contracts, registry/manifest, resolvers, ui components
  dynamic-renderer/  section-engine, page-renderer, section-renderer, widget-host
  layouts/       page-chrome containers (dynamic-page-layout, header/footer shells)
  i18n/          translations.ts (interface), en.ts, ru.ts, hy.ts, translate.pipe.ts, TranslateService
  pages/         top-level routed pages (home, cart, category, ...)
  components/    reusable standalone components used across features (product-card, telegram-login, ...)
  guards/        route guards (admin-auth guard, etc.)

Routing (`app.routes.ts`)

Locale-prefixed routes: /:lang/... (lang from LanguageService.currentLanguage()), plus root redirects.
Storefront: /, /catalog, /catalog/:id, /product/:id (legacy /item/:id and /category/:id[/items] redirect for compatibility).
Static/CMS pages resolve dynamically: /:lang/:staticPath (legacy /:lang/page/:key kept for compatibility) — no hardcoded page list, resolved from bootstrap.staticPages.
Project Editor: /edit/:section or /{lang}/edit/:section.
Admin/backoffice: /:lang/backoffice/**, guarded by adminAuthGuard (core/admin-auth/admin-auth.guard.ts) — dashboard, products (fully wired), categories/static-pages/transactions/orders/media (routed to BackofficeComingSoonPageComponent placeholders pending features). See docs/ADMIN.md.
Dev-only diagnostics: /__diagnostics (excluded from production).

i18n system

src/app/i18n/translations.ts defines the Translations interface — the single schema every locale file must satisfy (TypeScript enforces this at compile time: a missing key in any locale is a build error).
en.ts, ru.ts, hy.ts implement that interface, keyed identically and nested by feature area (header, footer, home, builder, dashboard, ...).
TranslateService resolves the active locale and exposes translated strings; TranslatePipe (| translate) is the template-facing API — never hardcode user-facing strings in templates, always add a key to all three locale files.
3 locales: en, ru, hy (Armenian). LanguageService tracks the active locale and drives the /:lang/ route prefix.
Adding a new UI string: add the key to the Translations interface first, then to en.ts/ru.ts/hy.ts in the same position (see docs/EDITOR.md for the pattern used by the field-description work).

Theming

3 tenant theme stylesheets: src/styles/themes/*.theme.scss.
Convention: each theme file defines CSS custom properties (--color-primary, --text-primary, --border-color, etc.) that mirror ThemeConfig.palette/typography/shadows/borderRadiusScale; components and widgets consume only these custom properties, never hardcoded hex values (ADR-008).
theme.mode (light | dark | system) and the palette are runtime-configurable per tenant via bootstrap and editable via the Project Editor's Theme section (docs/EDITOR.md).

State management

Signals-based facades, no NgRx. Every feature/domain exposes a facade (ProjectEditorFacade, CategoryFacade, ProductFacade, SearchFacade, AdminDashboardFacade, ...) built on Angular signals (signal, computed, effect), following ADR-007.
Components inject exactly one facade and read/write through it; no direct service or HTTP access from components (ADR-006).
Local component state (e.g. draft form values) stays in the component; cross-cutting/shared state lives in the facade.
Persistence for local-only features (Project Editor drafts, admin dashboard activity history) uses scoped localStorage keys behind a dedicated service (ProjectEditorDraftStorageService, AdminDashboardHistoryService) — never raw localStorage calls from components/facades.

Dynamic widget/section rendering from bootstrap JSON

Full detail in docs/ARCHITECTURE.md and docs/BACKEND_API.md#4-bootstrap. Summary: page config (bootstrap.pages) -> Section Engine (order/layout/visibility) -> Page Renderer -> Widget Host (resolves component via Widget Manifest + data via Data Source Resolver) -> widget component (props + resolved data only). Nothing in this pipeline calls an API directly except the Data Source Resolver, which delegates to CategoryFacade/ProductFacade.

4.9 KiB Raw Blame History