Skip to content

Architecture Notes

This document is the high-level architecture overview. Detailed rules live in the linked documents and should not be duplicated here.

OC3-first Approach

The project starts with OpenCart 3 as the primary implementation target. OpenCart 4 support is planned for a later stage and should be introduced through a compatibility layer instead of forcing early abstractions.

No Core Changes

OpenCart core files must not be modified. Theme behaviour should be implemented through theme files, extension-safe integration points, canonical OpenCart conventions, and documented build or install steps.

Canonical OpenCart Conventions

OpenCart conventions come first. Custom routes, controllers, settings, language keys, templates, and future extensions should look native to the OpenCart ecosystem unless an architecture PR explicitly approves a deviation.

Naming rules are documented in docs/naming-conventions.md.

Source Separation

  • src/shared/ contains code and assets intended to be shared across OpenCart versions.
  • src/oc3/ contains OpenCart 3-specific implementation.
  • src/oc4/ is reserved for future OpenCart 4 compatibility work.

Shared code should remain version-aware only where necessary. Version-specific behaviour belongs in the matching oc3 or oc4 area.

Theme Name and Prefix

The OpenCart 3 theme directory is shop3. Custom project entities use the shop3_ prefix. The future OpenCart 4 layer reserves shop4 and must not change OC3 naming without a reviewed compatibility decision.

Theme Settings Engine

The future Theme Settings Engine provides one admin centre, independent settings sections, partial section saves, namespaced shop3_ keys, multi-store awareness, and low-read storefront configuration.

The approved design is documented in docs/theme-settings-engine.md. Implementation should happen in later focused PRs.

Documentation Architecture

The documentation map is the index of all project docs and their translation status: docs/documentation-map.md.

The roadmap is the source for phase planning and current focus: docs/roadmap.md.

Governance and Boundaries

Engineering principles, system boundaries, community input, product philosophy, licensing direction, and technical debt policy are documented separately:

  • 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

A build pipeline for frontend assets will be added later under build/ and supporting tools under tools/. Until then, avoid undocumented build assumptions and keep asset loading simple.

Asset strategy is documented in docs/asset-pipeline.md.

Small PRs

Product code and documentation changes should be delivered through small, reviewable pull requests. Large systems require architecture/design documentation before implementation.