docs: OEP-65 reframe around build-time shell architecture

Reframe OEP-65 to match the frontend-base reference implementation:
build-time composition of apps into sites via a shared shell, replacing
the dropped runtime module federation approach. Rework the glossary and
ADRs to the new vocabulary (App, App Repository, Site, Shell, Shell
Architecture, Slot, Widget), rename ADR-0003 to "Frontend Sites", remove
the obsolete federation diagrams, and fix the "Composability" label typo.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: arbrandes

oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst

@@ -1,7 +1,7 @@
-.. _Create a unified platform repository:
+.. _Create a unified platform library:
 
-Create a unified platform repository
-####################################
+Create a unified platform library
+#################################
 
 Status
 ******
@@ -11,14 +11,14 @@ Accepted
 Summary
 *******
 
-This ADR proposes combining a number of repositories into a single, unified frontend platform library as a migration strategy for implementing :ref:`OEP-65 <OEP-65 Frontend Composibility>`.  This library is named `frontend-base <https://github.com/openedx/frontend-base>`_.
+This ADR proposes combining a number of repositories into a single, unified frontend platform library as a migration strategy for implementing :ref:`OEP-65 <OEP-65 Frontend Composability>`.  This library is named `frontend-base <https://github.com/openedx/frontend-base>`_.
 
 Context
 *******
 
-OEP-65 proposes adopting webpack :term:`module federation` for Open edX :term:`micro-frontends <Micro-frontend>` (MFEs) as a means to enable :term:`runtime module loading` and :term:`shared dependencies` in the :term:`Open edX frontend`. The OEP lays out a series of changes necessary to enable these capabilities, which it refers to as building a "reference implementation" of runtime module loading and shared dependencies.
+OEP-65 proposes composing the :term:`Open edX Frontend` from independently developed :term:`apps <App>` at build time - into one or more :term:`Sites <Site>` built by a shared :term:`Shell` - as a means to enable build-time composability and :term:`shared dependencies <Shared Dependencies>`. The OEP lays out a series of changes necessary to enable these capabilities, which it refers to as building a "reference implementation".
 
-This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the :term:`module architecture`, as opposed to the historical :term:`micro-frontend architecture` that has existed prior to OEP-65.
+This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the :term:`Shell Architecture`, as opposed to the historical :term:`Micro-frontend Architecture` that has existed prior to OEP-65.
 
 The bulk of the work to build OEP-65's reference implementation is related to the *library repositories* that MFEs depend on:
 
@@ -28,7 +28,7 @@ The bulk of the work to build OEP-65's reference implementation is related to th
 * frontend-component-header
 * frontend-component-footer
 
-It will also involve the creation of a new :term:`Shell` to initialize the frontend at runtime and load existing MFEs as :term:`modules <Module>`. Prior to this decision, we might have considered putting the shell in its own repository as well:
+It will also involve the creation of a new :term:`Shell` to initialize the frontend and compose existing MFEs into a :term:`Site` as :term:`apps <App>`. Prior to this decision, we might have considered putting the shell in its own repository as well:
 
 * frontend-app-shell
 
@@ -37,12 +37,12 @@ There are several related concerns which influence our strategy for migrating th
 Significant API changes
 =======================
 
-The creation of the shell and the move toward using :term:`plugins <Plugin Module>` and module federation is expected to significantly change the API surface across our various libraries.
+The creation of the shell and the move toward composing :term:`apps <App>` is expected to significantly change the API surface across our various libraries.
 
 ``frontend-platform``
 ---------------------
 
-As the shell takes responsibility for much of what ``frontend-platform`` provides to MFEs in the micro-frontend architecture, many of the APIs it exposes will become internal to the shell. We will also likely need to add new APIs for interactions between the shell and modules.
+As the shell takes responsibility for much of what ``frontend-platform`` provides to MFEs in the :term:`Micro-frontend Architecture`, many of the APIs it exposes will become internal to the shell. We will also likely need to add new APIs for interactions between the shell and apps.
 
 ``frontend-build``
 ------------------
@@ -57,7 +57,7 @@ The header and footer will be owned by the shell and need not be libraries any m
 ``frontend-plugin-framework``
 -----------------------------
 
-We expect ``frontend-plugin-framework`` to be folded into ``frontend-platform`` to unify the two, as they will be intimately tied to each other going forward. We'll also be creating new APIs around loading plugins that support module federation.
+We expect ``frontend-plugin-framework`` to be folded into ``frontend-base`` to unify it with the rest of the runtime library, as they will be intimately tied to each other going forward. We'll also be creating new APIs around composing :term:`widgets <Widget>` into :term:`slots <Slot>`.
 
 ``frontend-app-*`` Repositories
 -------------------------------
@@ -77,7 +77,7 @@ We also feel the need to continue to modernize our library repositories by adopt
 Deprecation of the micro-frontend architecture
 ==============================================
 
-As described in OEP-65, we're migrating from the :term:`micro-frontend architecture`, where each MFE is a standalone, independently deployed app, to a :term:`module architecture` where the MFEs are modules loaded into a common :term:`Shell` which owns the header, footer, initialization, and shared dependencies.
+As described in OEP-65, we're migrating from the :term:`Micro-frontend Architecture`, where each MFE is a standalone, independently deployed app, to a :term:`Shell Architecture` where the MFEs become :term:`apps <App>` composed into a common :term:`Shell` which owns the header, footer, initialization, and shared dependencies.
 
 One way or another, this is a paradigm shift that will involve breaking changes and migration work on behalf of community members. We would like to provide a clear a path forward for operators, developers, and maintainers to adopt the module architecture. We believe that a clean break and a cohesive and clear platform for modules is more approachable than a more granular deprecation of certain features and code in the existing library repositories.
 
@@ -100,24 +100,23 @@ Development tool configurations
 
 The library will provide base ESLint, Jest, TypeScript, and Webpack configurations. ESLint, Jest, and TypeScript will be similar to what ``frontend-build`` provides.
 
-The webpack configurations will support a variety of build targets for the new module architecture, as well as application MFE configurations to enable us to migrate to the new unified platform library in a backwards compatible way. The new build targets include:
+The webpack configurations will support a variety of build targets for the new :term:`Shell Architecture`, as well as application MFE configurations to enable us to migrate to the new unified platform library in a backwards compatible way. The new build targets include:
 
-* A production configuration suitable for deploying the MFE's modules to be consumed via module federation.
-* A release configuration which will package those same modules to be released as an npm package for use as direct plugins.
-* A development server configuration to serve the MFE's modules to be consumed locally via module federation, complete with hot module reloading.
-* A development server configuration to serve the MFE's modules inside a shell as direct plugins.
+* A production configuration suitable for building an :term:`App` into a deployable :term:`Site`.
+* A release configuration which packages an :term:`App Repository`'s :term:`apps <App>` as an npm package for build-time inclusion in a :term:`Site`.
+* A development server configuration to serve an :term:`App` inside a :term:`Shell`, complete with hot module reloading.
 
 These webpack configurations will be exposed via a function like ``frontend-build``'s '``createConfig`` so that they can be modified and extended as necessary by the MFEs.
 
 CLI tool
 ========
 
-Similar to ``fedx-scripts`` provided by ``frontend-build``, the ``frontend-base`` library will provide a CLI tool. This tool will expose commands to run the above webpack configurations, as well as other commands related to frontend projects. The rationale and details of frontend projects and these CLI commands are the subject of a future ADR.
+Similar to ``fedx-scripts`` provided by ``frontend-build``, the ``frontend-base`` library will provide a CLI tool. This tool will expose commands to run the above webpack configurations, as well as other commands related to building and developing :term:`Sites <Site>`. The rationale and details of these CLI commands are the subject of a future ADR.
 
 Consequences
 ************
 
-This approach allows us to treat the :term:`module architecture` as an independent effort, as opposed to a set of features that need to fit in with the existing :term:`micro-frontend architecture`. We greatly reduce or eliminate the risk of regressions in libraries that the entire community relies on while we build a replacement which resembles and borrows code from them, but is otherwise significantly different. This division makes it explicitly clear which features are used by the old architecture and which are used by the new one.
+This approach allows us to treat the :term:`Shell Architecture` as an independent effort, as opposed to a set of features that need to fit in with the existing :term:`Micro-frontend Architecture`. We greatly reduce or eliminate the risk of regressions in libraries that the entire community relies on while we build a replacement which resembles and borrows code from them, but is otherwise significantly different. This division makes it explicitly clear which features are used by the old architecture and which are used by the new one.
 
 Further, it means we can migrate to the new architecture in a backwards compatible way by atomically migrating MFEs to use the new `frontend-base <https://github.com/openedx/frontend-base>`_ library, again, without running the risk of destabilizing existing libraries with multiple breaking changes over time.
 
@@ -126,10 +125,10 @@ We believe this is a reasonable migration strategy given the generally low rate
 References
 **********
 
-* :ref:`OEP-65: Frontend Composability <OEP-65 Frontend Composibility>`
+* :ref:`OEP-65: Frontend Composability <OEP-65 Frontend Composability>`
 * :ref:`OEP-65 Frontend Glossary <Frontend Glossary>`
 * :ref:`ADR-0002: Frontend App Migrations <Frontend App Migrations>`
-* :ref:`ADR-0003: Frontend Projects <Frontend Projects>`
+* :ref:`ADR-0003: Frontend Sites <Frontend Sites>`
 
 Change History
 **************
@@ -140,6 +139,12 @@ Change History
 * Document created
 * `Pull request #598 <https://github.com/openedx/openedx-proposals/pull/598>`_
 
+2026-07-13
+==========
+
+* Updated terminology to match the ``frontend-base`` reference implementation: build-time composition of :term:`apps <App>` into :term:`Sites <Site>` via the :term:`Shell`, in place of runtime module federation. Renamed "Module Architecture" to :term:`Shell Architecture`.
+* Retitled from "Create a unified platform repository" to "Create a unified platform library" (and renamed the file accordingly), since ``frontend-base`` is a library.
+
 2024-09-13
 ==========