adds upgrade guide and apidocs

.gitbook.yaml

@@ -98,4 +98,14 @@ redirects:
     guides/installation/setups/devenv.html: guides/installation/legacy-setups/devenv-setup.html
     guides/installation/setups/symfony-cli.html: guides/installation/legacy-setups/symfony-cli-setup.html
     guides/installation/setups/devenv-options.html: guides/installation/legacy-setups/devenv-options.html
-    guides/installation/setups/: guides/installation/
+    guides/installation/setups/: guides/installation/
+    guides/plugins/plugins/administration/system-updates/meteor-components.html: guides/upgrades-migrations/administration/meteor-components.html
+    guides/plugins/plugins/administration/system-updates/pinia.html: guides/upgrades-migrations/administration/pinia.html
+    guides/plugins/plugins/administration/system-updates/vue3.html: guides/upgrades-migrations/administration/vue3.html
+    guides/plugins/plugins/administration/system-updates/vite.html: guides/upgrades-migrations/administration/vite.html
+    guides/plugins/plugins/administration/system-updates/vue-migration-build.html: guides/upgrades-migrations/administration/vue-migration-build.html
+    guides/plugins/plugins/administration/system-updates/vue-native.html: guides/upgrades-migrations/administration/vue-native.html
+    resources/references/upgrades/core/translation/extension-translation.html: guides/upgrades-migrations/extension-translation.html
+    resources/references/upgrades/core/translation/language-pack-migration.html: guides/upgrades-migrations/language-pack-migration.html
+    resources/references/upgrades/administration/: guides/upgrades-migrations/administration/
+    resources/references/upgrades/: guides/upgrades-migrations/

.wordlist.txt

@@ -834,6 +834,7 @@ SDKs
 SEO
 SEOs
 SFC
+SFCs
 SFTP
 SHA
 SKEs
@@ -1041,6 +1042,7 @@ VersionDataPayloadField
 VersionField
 VirtualHosts
 Vite
+Vite's
 VitePress
 Vitepress
 Vitest

concepts/api/admin-api.md

@@ -1,12 +1,18 @@
 ---
 nav:
   title: Admin API
-  position: 20
+  position: 60
 
 ---
 
 # Admin API
 
+The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication.
+
+These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times.
+
 The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems.
 
-For more information, refer to the [Guides section](../../guides/integrations-api/index.md).
+For details on endpoints, authentication methods, schemas, and request formats, always refer to the Admin API documentation.
+
+<PageRef page="https://shopware.stoplight.io/docs/admin-api/8d53c59b2e6bc-shopware-admin-api" title="Admin API – Stoplight Reference" target="_blank" />

concepts/api/index.md

@@ -7,8 +7,17 @@ nav:
 
 # API
 
-The Shopware API allows developers to interact with and integrate Shopware with other systems and applications. It provides a set of services that enable developers to perform various operations, such as managing products, customers, orders, and shopping carts.The API supports both read and write operations, allowing developers to retrieve information from Shopware and make modifications or additions to the e-commerce platform. By leveraging the Shopware API, developers can extend the functionality of Shopware, integrate it with external systems, and create seamless experiences for managing and operating online stores.
+Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform.
 
-Shopware supports two major functional APIs: the Store API and the Admin API. These APIs serve different purposes. The Store API is designed to interact with the front-end or storefront of a Shopware online store while the Admin API is intended for administrative operations related to managing the back-end of the Shopware platform.
+Two functional APIs are available, each representing a different integration surface:
 
-The API documentation provides details on the available endpoints, request/response formats, authentication mechanisms, and data structures. It supports different authentication methods, including token-based authentication and OAuth 2.0, to ensure secure communication between the API client and the Shopware platform.
+* **Store API**: customer-facing interactions
+* **Admin API**: administrative and system-level operations
+
+Both APIs use HTTP and exchange JSON payloads. The Administration API requires OAuth 2.0 authentication, whereas the Store API is publicly accessible and only requires contextual headers, with authentication needed for customer-specific endpoints. While they serve different purposes within the platform, they share some underlying design principles and structural patterns:
+
+* Search criteria abstraction for filtering, sorting, and pagination
+* Structured JSON request/response bodies
+* Header-based contextual behavior
+
+These patterns form the foundation of integration development.

concepts/api/store-api.md

@@ -1,35 +1,17 @@
 ---
 nav:
   title: Store API
-  position: 10
+  position: 50
 
 ---
 
 # Store API
 
-Every interaction between the store and a customer can be modeled using the Store API. It serves as a normalized layer or an interface to communicate between customer-facing applications and the Shopware Core. It can be used to build custom frontends like SPAs, native apps, or simple catalog apps. It doesn't matter what you want to build as long as you are able to consume a JSON API via HTTP.
+The Store API represents the customer-facing surface of Shopware. It is designed for storefront/frontend-related interactions such as product browsing, cart handling, checkout, and customer account management. It exposes only data that is relevant and safe for frontend use and supports both anonymous and authenticated customers.
 
-![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../assets/concepts-api-storeApiLogic.svg)
+The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services.
 
-Whenever additional logic is added to Shopware, the method of the corresponding service is exposed via a dedicated HTTP route. At the same time, it can be programmatically used to provide data to a controller or other services in the stack. This way, you can ensure that there is always common logic between the API and the Storefront and almost no redundancy. It also allows us to build core functionalities into our Storefront without compromising support for our API consumers.
+For details on endpoints, authentication methods, schemas, and request formats, always refer to the Store API documentation.
+<PageRef page="https://shopware.stoplight.io/docs/store-api/7b972a75a8d8d-shopware-store-api" title="Store API – Stoplight Reference" target="_blank" />
 
-## Extensibility
-
-Using plugins, you can add custom routes to the Store API \(as well as any other routes\) and also register custom services. We don't force developers to provide API coverage for their functionalities. However, if you want to support headless applications, ensure that your plugin provides its functionalities through dedicated routes.
-
-<PageRef page="../../guides/plugins/plugins/framework/store-api/" />
-
-## Store API and the traditional TWIG storefront
-
-When using the server-side rendered TWIG storefront, the Store API is not used.
-Instead, the storefront uses custom [storefront controllers](../../guides/plugins/plugins/storefront/add-custom-controller.md) which internally use the Store API to fetch data.
-
-The storefront controllers are optimized for the usage in our TWIG storefront. And the biggest difference is the way that authentication and authorization are handled.
-As the Store-API is a proper REST API, the main design is stateless, which means authentication info needs to be provided via the request headers in form of the `sw-context-token`.
-The storefront relies on the session to store the authentication info, that way you do not have to handle the authentication manually with every request.
-
-## What next?
-
-* To start working with the Store API, check out our [Quick Start guide](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) and explore all endpoints in our reference guide.
-
-* An interesting project based on the Store API is [Composable Frontends](../../../frontends/).
+Shopware provides [Composable Frontends](https://frontends.shopware.com/) as a headless frontend implementation based on the Store API.

concepts/framework/architecture/index.md

@@ -5,6 +5,36 @@ nav:
 
 ---
 
-# Architecture
+# Shopware 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.
+Shopware follows a modular, API-first architecture built on top of Symfony and modern frontend technologies. The platform separates concerns into clearly defined layers, allowing storefront experiences, administrative tooling, and core business logic to evolve independently while sharing a common backend foundation.
+
+At a high level, the system consists of three primary domains:
+
+* **Core** — the backend foundation containing business logic, data abstraction, APIs, and extension mechanisms.
+* **Storefront** — the customer-facing presentation layer responsible for rendering sales channels and interacting with the Store API.
+* **Administration** — the management interface used by merchants and operators to configure, manage, and operate the platform.
+
+These domains are unified through a shared API layer and a consistent plugin system, enabling extensibility without tightly coupling features to presentation layers.
+
+## Architectural principles
+
+The Shopware architecture is guided by several core principles:
+
+* **API-first design** — all functionality is exposed via APIs, enabling headless and composable commerce scenarios.
+* **Separation of concerns** — frontend experiences (storefront/admin) are decoupled from backend logic.
+* **Extensibility** — plugins integrate through events, services, and extension points rather than modifying core code.
+* **Asynchronous processing** — background tasks (indexing, messaging, integrations) are handled via message queues and workers.
+* **Domain-driven structure** — business logic is organized around commerce domains rather than UI features.
+
+## Core components
+
+The architecture centers around the Shopware Core, which provides:
+
+* Data Abstraction Layer (DAL) for database interaction
+* Business services and domain logic
+* Sales Channel and Store APIs
+* Plugin and event system
+* Messaging and scheduled task infrastructure
+
+The Storefront and Administration layers consume these services rather than duplicating logic, ensuring consistency across channels.