Documentation Map
This document is the index of project documentation. It defines purpose, tier, status, translation status, and update triggers.
English documentation is the source of truth. Russian files in docs/ru/ are translations only. If English and Russian conflict, English wins.
Status Values
existing- the document exists in the repository.planned- the document is intentionally planned but not yet created.future- the document belongs to a later advanced phase.
Translation Status Values
source- English source-of-truth document.translated- Russian translation exists.not translated- no Russian translation is available yet.translation only- Russian file mirrors an English source.
Documentation Tiers
- Tier 1 - required now.
- Tier 2 - required before UI implementation.
- Tier 3 - required before release.
- Tier 4 - future or advanced.
Current Documents
| Document | Purpose | Tier | Status | Translation Status | When to Update |
|---|---|---|---|---|---|
docs/index.md |
Documentation home and orientation. | Tier 1 | existing | translated | Update when core navigation or project positioning changes. |
docs/architecture.md |
High-level architecture overview and links to detailed rules. | Tier 1 | existing | translated | Update when architecture boundaries or linked source documents change. |
docs/roadmap.md |
Phases, statuses, and current focus. | Tier 1 | existing | translated | Update when phase status, current focus, or sequencing changes. |
docs/documentation-map.md |
Documentation index, tiers, status, and translation status. | Tier 1 | existing | translated | Update when documents are added, renamed, retired, or translated. |
docs/naming-conventions.md |
Canonical OpenCart naming and shop3_ prefix rules. |
Tier 1 | existing | translated | Update when naming rules expand or change. |
docs/development-workflow.md |
Branch, commit, PR, review, and merge workflow. | Tier 1 | existing | not translated | Update when GitHub workflow or merge policy changes. |
docs/pr-checklist.md |
Required PR validation checklist. | Tier 1 | existing | not translated | Update when validation requirements change. |
docs/theme-settings-engine.md |
Approved Theme Settings Engine architecture. | Tier 1 | existing | translated | Update before settings implementation changes the contract. |
docs/coding-standards.md |
Practical PHP, Twig, CSS, and JS standards. | Tier 2 | existing | not translated | Update when coding expectations or style rules change. |
docs/environment-strategy.md |
Domain and environment roles. | Tier 1 | existing | not translated | Update when domain roles or environment policy changes. |
docs/ops-workflow.md |
Operational issue workflow for server work. | Tier 1 | existing | not translated | Update when OPS logging rules change. |
docs/deployment-strategy.md |
Future deployment flow and guardrails. | Tier 3 | existing | not translated | Update before production or automated deployment work. |
docs/theme-structure.md |
Theme directory and file ownership. | Tier 2 | existing | not translated | Update when theme structure changes. |
docs/compatibility-policy.md |
OC3, future OC4, and ecosystem compatibility rules. | Tier 2 | existing | not translated | Update when compatibility boundaries change. |
docs/system-boundaries.md |
Responsibility boundaries for theme, modules, core, integrations, layout, and settings. | Tier 1 | existing | not translated | Update when ownership boundaries change. |
docs/design-system.md |
Design token and UI foundation plan. | Tier 2 | existing | not translated | Update before UI implementation changes tokens or component rules. |
docs/asset-pipeline.md |
Asset loading and future build pipeline strategy. | Tier 2 | existing | not translated | Update before adding build tools or asset conventions. |
docs/performance-strategy.md |
Storefront performance principles and constraints. | Tier 2 | existing | not translated | Update when performance tactics or budgets change. |
docs/architecture-principles.md |
Practical engineering principles. | Tier 1 | existing | not translated | Update when project-wide engineering principles change. |
docs/community-driven-development.md |
How ideas, merchant feedback, and donations influence roadmap priority. | Tier 1 | existing | not translated | Update when community input workflow changes. |
docs/product-philosophy.md |
Long-term product/platform direction. | Tier 1 | existing | not translated | Update when product philosophy changes. |
docs/licensing-model.md |
Licensing direction, not final legal text. | Tier 3 | existing | not translated | Update before choosing or changing the actual licence. |
docs/monetisation-strategy.md |
Future paid ecosystem options around a useful free core. | Tier 3 | existing | not translated | Update when monetisation direction changes. |
docs/community-governance.md |
How decisions are accepted, deferred, or rejected. | Tier 1 | existing | not translated | Update when governance process changes. |
docs/trademark-policy.md |
Practical branding and official identity boundaries. | Tier 3 | existing | not translated | Update before public brand launch or marketplace release. |
docs/extension-marketplace-policy.md |
Extension quality and compatibility expectations. | Tier 3 | existing | not translated | Update before ecosystem or marketplace work. |
docs/technical-debt.md |
Technical debt register and template. | Tier 1 | existing | not translated | Update when debt is added, resolved, or reprioritised. |
docs/adr/README.md |
ADR process and naming. | Tier 1 | existing | not translated | Update when decision-record rules change. |
docs/docs-site.md |
Docs site strategy for docs.opencart.link. |
Tier 1 | existing | not translated | Update when docs site deployment strategy changes. |
Planned Future Documents
| Document | Purpose | Tier | Status | Translation Status | When to Update |
|---|---|---|---|---|---|
docs/security-policy.md |
Security expectations for settings, credentials, admin, and deployments. | Tier 3 | planned | not translated | Create before admin settings or release work. |
docs/release-strategy.md |
Packaging, installer, demo content, updater, and release flow. | Tier 3 | planned | not translated | Create before public release engineering. |
docs/testing-strategy.md |
Manual and automated testing approach. | Tier 3 | planned | not translated | Create before release candidates or larger implementation. |
docs/oc4-migration-strategy.md |
Future OC4 migration layer. | Tier 4 | future | not translated | Create before OC4 implementation begins. |
docs/localisation-strategy.md |
Language and translation workflow. | Tier 4 | future | not translated | Create before multilingual release work. |
docs/multistore-strategy.md |
Advanced multistore behaviour. | Tier 4 | future | not translated | Create before advanced multistore features. |
Maintenance Rules
- Keep global decisions in the relevant document, not only in PR descriptions.
- Use architecture/design PRs before implementing large systems.
- Update this map when documents are added, renamed, merged, retired, or translated.
- Keep OPS state in GitHub issues and product architecture in repository documentation.
- Do not create empty Russian placeholders for untranslated docs.