From be0e8fcf83a53cc997b50d196b4c54282bf82e42 Mon Sep 17 00:00:00 2001
From: sushmangupta <s.gupta@shopware.com>
Date: Thu, 26 Feb 2026 17:27:03 +0100
Subject: [PATCH] shopware architecture - additional content

---
 .../framework/architecture/core-concepts.md   | 92 +++++++++++++++++++
 concepts/framework/architecture/index.md      | 70 ++++++++++++++
 2 files changed, 162 insertions(+)
 create mode 100644 concepts/framework/architecture/core-concepts.md

diff --git a/concepts/framework/architecture/core-concepts.md b/concepts/framework/architecture/core-concepts.md
new file mode 100644
index 0000000000..abbc91fa01
--- /dev/null
+++ b/concepts/framework/architecture/core-concepts.md
@@ -0,0 +1,92 @@
+---
+nav:
+  title: Core
+  position: 25
+---
+
+# Core
+
+The Core component represents the central backend foundation of Shopware. It provides the domain logic, data handling, APIs, and extensibility mechanisms that power both the Storefront and Administration components.
+
+Conceptually, the Core sits at the center of the platform architecture. While the Storefront and Administration provide user interfaces, the Core exposes functionality through structured APIs and services. All business logic, domain modeling, and system integrations are implemented within the Core to ensure consistency across different presentation layers.
+
+The Core is built on Symfony and follows modern backend design principles such as dependency injection, domain-driven organization, and event-based extensibility.
+
+## Main concerns
+
+The Core component is responsible for:
+
+* Managing business logic and domain services
+* Providing API interfaces (Store API and Admin API)
+* Handling data persistence and abstraction
+* Managing plugins and extensions
+* Supporting asynchronous processing
+* Providing integration points for external systems
+
+## Domain-driven architecture
+
+Shopware organizes the Core around commerce-related domains rather than technical layers. Examples include:
+
+* Products
+* Orders
+* Customers
+* Checkout
+* Pricing
+* Inventory
+
+Each domain encapsulates its own services, entities, and business rules. This structure helps maintain clear boundaries and improves extensibility.
+
+## Data abstraction layer (DAL)
+
+The Data Abstraction Layer (DAL) provides a consistent way to access and manipulate database entities. Instead of working directly with database queries, developers interact with repositories and entity definitions.
+
+Key responsibilities of the DAL include:
+
+* Entity definitions and associations
+* Validation and schema abstraction
+* Versioning and inheritance handling
+* Context-aware data access
+* Event dispatching during entity lifecycle changes
+
+The DAL ensures that all components access data consistently and enables powerful extension capabilities.
+
+## APIs and communication
+
+The Core exposes functionality through two primary APIs:
+
+* **Store API** — Public-facing API used by storefront applications and headless frontends. It supports anonymous access and customer-authenticated requests depending on the endpoint.
+* **Administration API** — OAuth 2.0 secured API used by the Administration SPA and external management integrations.
+
+Both APIs communicate over HTTP and exchange structured JSON payloads, allowing decoupled frontend implementations.
+
+## Plugin and extension system
+
+Extensibility is a fundamental design principle of Shopware. The Core provides multiple extension mechanisms:
+
+* Symfony event system
+* Service decoration
+* Entity extensions
+* Custom API routes
+* Dependency injection configuration
+
+Plugins integrate into the system without modifying core code, enabling safe upgrades and customization.
+
+## Messaging and asynchronous processing
+
+Certain operations are executed asynchronously to improve performance and scalability. The Core uses Symfony Messenger for background processing tasks such as:
+
+* Indexing and search updates
+* Scheduled tasks
+* Email sending
+* Integration workflows
+
+Message queues allow heavy operations to run outside the request lifecycle.
+
+## Interaction with other components
+
+The Core serves as the foundation for:
+
+* **Storefront** — Uses the Store API and domain services to render customer-facing pages.
+* **Administration** — Communicates via the Admin API to manage entities and configurations.
+
+By centralizing logic in the Core, Shopware ensures consistent behavior regardless of how functionality is accessed.
diff --git a/concepts/framework/architecture/index.md b/concepts/framework/architecture/index.md
index 35e8b3701a..40c3d7f034 100644
--- a/concepts/framework/architecture/index.md
+++ b/concepts/framework/architecture/index.md
@@ -8,3 +8,73 @@ nav:
 # Architecture
 
 On a high level, Shopware consists of multiple modules that separate the entire code base into logical units. Some modules are independent, and some depend on others.
+
+## Architectural overview
+
+High-level architectural overview of Shopware’s core system layers and supporting infrastructure.
+
+```mermaid
+flowchart TB
+  %% Entry
+  U[User (Customer / Admin)] -->|HTTPS| RP[Reverse Proxy / Load Balancer]
+
+  %% Application boundary
+  subgraph SW[Shopware 6 Application]
+    direction TB
+
+    %% Top-level modules
+    subgraph CORE[Core]
+      direction TB
+      DAL[Data Abstraction Layer (DAL)]
+      BL[Business Logic / Services]
+      API[Sales Channel API + Store API]
+      PLUG[Plugin System + Events]
+      SCHED[Scheduled Tasks]
+      MESSAGE[Symfony Messenger (Async)]
+    end
+
+    subgraph ADMIN[Administration]
+      direction TB
+      ADMUI[Admin UI (Vue)]
+      ADMAPI[Admin API (ACL / AuthZ)]
+      BUILDADM[Build Tooling (npm/webpack)]
+      ADMUI --> ADMAPI
+    end
+
+    subgraph STOREFRONT[Storefront]
+      direction TB
+      SFSSR[Storefront (Twig / Symfony Controllers)]
+      SFAPI[Store API / Sales Channel API Client]
+      BUILDSF[Build Tooling (npm/webpack)]
+      SFSSR --> SFAPI
+    end
+
+    %% Internal interactions
+    ADMIN --> API
+    STOREFRONT --> API
+    API --> DAL
+    BL --> DAL
+    PLUG --> BL
+    SCHED --> MESSAGE
+    BL --> MESSAGE
+  end
+
+  %% Infrastructure dependencies
+  DB[(MySQL / MariaDB)] <--> DAL
+  CACHE[(Redis: Cache / Sessions / Locks)] <--> SW
+  SEARCH[(Elasticsearch / OpenSearch)] <--> SW
+  FS[(Media Storage: Local FS / NFS / S3)] <--> SW
+
+  %% Async processing
+  MQ[(Async Transport: Redis / RabbitMQ / DB)] <--> MESSAGE
+  MESSAGE --> W[Workers / Consumers]
+  W --> DB
+  W --> SEARCH
+  W --> FS
+
+  %% External integrations
+  EXT[External Services\nPayment / Shipping / ERP / PIM / Tax / Email] <--> API
+  EXT <--> W
+
+  RP --> SW
+```