261ce6d55b
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).
55 lines
4.9 KiB
Markdown
55 lines
4.9 KiB
Markdown
# 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, categories, orders, transactions, users, moderation, media, monitoring, analytics. See `docs/BACKEND.md` for the data-source contract for each.
|
|
- 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.md#1-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`.
|