Skip to content

Architecture Notes

Это перевод английского документа docs/architecture.md. Английская версия является source of truth. Если перевод противоречит английскому документу, английский документ имеет приоритет.

Этот документ — верхнеуровневый обзор архитектуры. Детальные правила живут в связанных документах и не должны дублироваться здесь.

OC3-first Approach

Проект начинается с OpenCart 3 как основного target. Поддержка OpenCart 4 планируется позже через compatibility layer, без преждевременных абстракций внутри OC3 темы.

No Core Changes

Файлы ядра OpenCart не изменяются. Поведение темы реализуется через theme files, extension-safe integration points, канонические conventions OpenCart и документированные build/install steps.

Canonical OpenCart Conventions

Conventions OpenCart имеют приоритет. Custom routes, controllers, settings, language keys, templates и будущие extensions должны выглядеть нативно для OpenCart, если отдельный architecture PR не одобрил отклонение.

Правила naming описаны в docs/naming-conventions.md.

Source Separation

  • src/shared/ содержит код и assets, которые могут быть общими для разных версий OpenCart.
  • src/oc3/ содержит OpenCart 3-specific implementation.
  • src/oc4/ зарезервирован для будущей OpenCart 4 compatibility work.

Общий код должен учитывать версии только там, где это действительно нужно. Version-specific behaviour должен жить в oc3 или oc4.

Theme Name and Prefix

Имя темы OpenCart 3: shop3. Custom project entities используют prefix shop3_. Будущий OpenCart 4 layer резервирует shop4 и не должен менять OC3 naming без reviewed compatibility decision.

Theme Settings Engine

Будущий Theme Settings Engine должен дать один admin centre, независимые sections, partial section saves, namespaced shop3_ keys, multi-store awareness и low-read storefront configuration.

Approved design описан в docs/theme-settings-engine.md. Implementation должна идти позже отдельными focused PR.

Documentation Architecture

Карта документации: docs/documentation-map.md.

Roadmap для phase planning и current focus: docs/roadmap.md.

Governance and Boundaries

Engineering principles, system boundaries, community input, product philosophy, licensing direction и technical debt policy описаны отдельно:

  • docs/architecture-principles.md
  • docs/system-boundaries.md
  • docs/community-driven-development.md
  • docs/product-philosophy.md
  • docs/licensing-model.md
  • docs/technical-debt.md

Asset Pipeline

Frontend asset pipeline будет добавлен позже в build/ и tools/. До этого нельзя вводить недокументированные build assumptions.

Asset strategy описана в docs/asset-pipeline.md.

Small PRs

Product code и documentation changes должны идти через маленькие reviewable PR. Большие системы требуют architecture/design documentation до implementation.