Skip to content

Architecture Principles

These principles define the engineering DNA of the Shop3 OpenCart theme project.

The project does not blindly apply enterprise patterns. OpenCart ecosystem compatibility matters, legacy ecosystem realities must be respected, and abstractions require justification.

Engineering Principles

KISS

Prefer simple, predictable solutions. Avoid cleverness that makes debugging, extension compatibility, or review harder.

DRY

Avoid harmful duplication, but do not introduce abstractions too early. Duplication can be acceptable when the abstraction would be premature or incompatible with OpenCart conventions.

YAGNI

Do not build systems before they are justified. Build the smallest useful system for the approved phase and evolve it through reviewable PRs.

PSR-12

Follow PSR-12 formatting and style where compatible with OpenCart conventions. OpenCart file placement, routes, class names, and extension conventions take precedence when they conflict.

Separation of Concerns

Theme, modules, settings, integrations, layouts, and infrastructure should have clear responsibility boundaries.

Convention over Cleverness

Prefer canonical OpenCart conventions over custom architecture. Routes, controllers, language keys, config keys, templates, and extension structure should feel native to OpenCart.

Compatibility over Abstraction

Avoid abstractions that reduce compatibility with the OpenCart ecosystem, common modules, multistore behaviour, language handling, or extension expectations.

Progressive Enhancement

The storefront should remain functional without excessive frontend dependency requirements.

Performance First

Evaluate architecture decisions through storefront performance impact. Avoid repeated database reads, unnecessary asset weight, excessive DOM complexity, and heavy dependencies without clear value.

Maintainability over Short-term Speed

Avoid hacks that create long-term maintenance cost. Temporary workarounds must be visible and have a removal path.

Small Reviewable Changes

Prefer small PRs and incremental architecture evolution.

Documentation Before Large Systems

Large systems require architecture or design documentation before implementation.

Project-specific Guardrails

  • No OpenCart core edits.
  • OC3-first, OC4-compatible mindset.
  • Predictable naming conventions.
  • Cache-aware architecture.
  • Partial persistence over giant payloads.
  • Defaults over excessive configuration.
  • Admin UX simplicity.
  • Storefront performance priority.
  • Long-term maintainability over short-term speed.

Review Rule

If a PR introduces a new abstraction, custom convention, dependency, or compatibility risk, the PR Notes must explain why it is justified and how it respects OpenCart ecosystem realities.