docs: integrate remaining technical and advanced pages with deep dive

claude · claude · commit 9be4e1d3c5d5 · 2026-05-02T17:13:43.000Z
Builds on the deep-dive split (commit fcf5190) by wiring the rest of the documentation into the new structure, so readers have a clear learning path and every page knows where it sits. Top-level technical pages - concept.md: add a "How to Read the Technical Section" callout near the top, listing three reading paths (just-the-architecture, full picture, implementation deep dive) so readers pick a route before diving in. - dx.md: framing paragraph that positions the page as the practical counterpart to concept.md. - cloud.md: explicit "two questions answered" framing. - technology/overview.md: narrative intro about the cyclical pattern (server-rendered → SPA → server-driven again) and a pointer into the detailed comparisons. New page - technical/glossary.md: alphabetical reference for terms used across the technical section (HDA, SPA, MPA, OData, RAP, RTTI, S-RTTI, Draft, Stateful Session, UI5 Over the Wire, …). Each entry links to the section that explains the term in context. - Sidebar: added under Technical Insights → Glossary. Cross-links from /advanced/ into the deep dive - downporting.md, renaming.md, builds.md → tools and tradeoffs. - local.md → abapmerge tool, system-footprint section. - stateful.md → drafts section + Glossary. - rfc.md → architecture chapter. - fiori.md → RAP comparison + launchpad config. - extensibility/{user_exits, custom_js, frontend, custom_control} → all linked to "Inside an App → The Initial Request" and "Sending JavaScript Over the Wire", which explain the underlying framework mechanics. All internal doc links audited — no broken targets. https://claude.ai/code/session_011kvL4ihgqWYQa2SSufEaKv
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
@@ -279,6 +279,7 @@ export default defineConfig({
               { text: "abapmerge", link: "/technical/tools/abapmerge" },
             ],
           },
+          { text: "Glossary", link: "/technical/glossary" },
         ],
       },
       {
diff --git a/docs/advanced/builds.md b/docs/advanced/builds.md
@@ -12,3 +12,9 @@ For heavy abap2UI5 use, consider building your own version by defining a custom
 Make your own abap2UI5 build with the [builder](https://github.com/abap2UI5/builder).
 
 <img width="700" alt="abap2UI5 builder interface for generating custom namespaced builds" src="https://github.com/user-attachments/assets/7c7f55d4-6667-4036-bc71-4cd7472f2ae9" />
+
+## See Also
+
+- **[Renaming](/advanced/renaming)** — picking a custom namespace.
+- **[Local](/advanced/local)** — bundle the framework into a single class instead of a custom build.
+- **[abapmerge](/technical/tools/abapmerge)** — the merge tool used by the local build.
diff --git a/docs/advanced/downporting.md b/docs/advanced/downporting.md
@@ -16,3 +16,8 @@ Some sample projects and other repositories also ship a downported version. Chec
 
 ## Functionality
 For more on the downport feature, see the blog post [Running abap2UI5 on older R/3 Releases](https://www.linkedin.com/pulse/running-abap2ui5-older-r3-releases-downport-compatibility-abaplint-mjkle).
+
+## See Also
+
+- **[Trade-offs and Compatibility](/technical/deep_dive/tradeoffs#compatibility-and-downporting)** — why abap2UI5 keeps a single codebase compatible with both Standard ABAP and ABAP Cloud.
+- **[abaplint](/technical/tools/abaplint)** — the tool that produces the `702` branch automatically.
diff --git a/docs/advanced/extensibility/custom_control.md b/docs/advanced/extensibility/custom_control.md
@@ -14,3 +14,9 @@ Write the JS code for your new custom control. Copy an existing control from [Ap
 ## Backend
 Extend the custom control view class by adding a method and defining the new control's properties:
 [z2ui5_cl_xml_view_cc.clas.abap](https://github.com/abap2UI5/abap2UI5/blob/main/src/02/z2ui5_cl_xml_view_cc.clas.abap)
+
+## See Also
+
+- **[Inside an App → Sending JavaScript Over the Wire](/technical/deep_dive/lifecycle#sending-javascript-over-the-wire)** — the underlying mechanism that lets you ship JS to the frontend.
+- **[Custom JS](/advanced/extensibility/custom_js)** — for one-off JavaScript without building a full control.
+- **[Frontend](/advanced/extensibility/frontend)** — local setup for building and testing controls.
diff --git a/docs/advanced/extensibility/custom_js.md b/docs/advanced/extensibility/custom_js.md
@@ -30,3 +30,8 @@ Below is a starting point that works. The `_generic` method creates a custom XML
 
 ENDMETHOD.
 ```
+
+## See Also
+
+- **[Inside an App → Sending JavaScript Over the Wire](/technical/deep_dive/lifecycle#sending-javascript-over-the-wire)** — why this works and how the framework forwards JavaScript to the frontend.
+- **[Custom Control](/advanced/extensibility/custom_control)** — wrap reusable JS into proper UI5 controls.
diff --git a/docs/advanced/extensibility/frontend.md b/docs/advanced/extensibility/frontend.md
@@ -31,3 +31,8 @@ Convert the UI5 app to stringified ABAP:
 cd ..
 npm run auto_app2abap
 ```
+
+## See Also
+
+- **[Inside an App → The Initial Request](/technical/deep_dive/lifecycle#the-initial-request)** — why the static frontend shell lives as a string inside the HTTP handler.
+- **[Custom Control](/advanced/extensibility/custom_control)** — extend the shell with new UI5 controls.
diff --git a/docs/advanced/extensibility/user_exits.md b/docs/advanced/extensibility/user_exits.md
@@ -36,3 +36,9 @@ CLASS zcl_a2ui5_user_exit IMPLEMENTATION.
 
 ENDCLASS.
 ```
+
+## See Also
+
+- **[Inside an App → The Initial Request](/technical/deep_dive/lifecycle#the-initial-request)** — what `set_config_http_get` actually customizes.
+- **[Inside an App → Drafts](/technical/deep_dive/lifecycle#drafts-stateful-feel-stateless-backend)** — what `draft_exp_time_in_hours` controls under the hood.
+- **[General Setup](/configuration/setup)** — common things to configure via the user exit.
diff --git a/docs/advanced/fiori.md b/docs/advanced/fiori.md
@@ -88,3 +88,8 @@ On the ABAP side, the app receives the Fiori startup parameters (like the app cl
 
   ENDMETHOD.
 ```
+
+## See Also
+
+- **[RAP vs. abap2UI5](/technical/technology/rap)** — how the two approaches differ, and where they complement each other.
+- **[Fiori Launchpad](/configuration/launchpad)** — embedding standalone abap2UI5 apps in the launchpad (as opposed to inside an FE object page).
diff --git a/docs/advanced/local.md b/docs/advanced/local.md
@@ -23,3 +23,9 @@ For full sources and the latest build, see the [abap2UI5-local repository](https
 The `abap2UI5-local` build is produced by [abapmerge](/technical/tools/abapmerge): all framework classes are merged into one class. You install that class plus a database table for session storage, then point an HTTP service at it the same way as in the [Quickstart](/get_started/quickstart).
 
 The resulting app behaves like any other abap2UI5 app — same APIs, same view DSL, same event flow. The difference is purely in how the framework reaches the system.
+
+## See Also
+
+- **[abapmerge](/technical/tools/abapmerge)** — the tool that produces the local build.
+- **[Builder](/advanced/builds)** — for full custom builds with namespace + add-ons.
+- **[Trade-offs → System Footprint](/technical/deep_dive/tradeoffs#system-footprint)** — why the framework is small enough to bundle into a single class.
diff --git a/docs/advanced/renaming.md b/docs/advanced/renaming.md
@@ -16,3 +16,8 @@ For more on renaming ABAP artifacts, see:
 
 For more background, see the blog post:
 [Renaming of ABAP Artifacts - The Power of abaplint and abapGit in ABAP Development](https://www.linkedin.com/pulse/renaming-abap-artifacts-power-abaplint-github-actions-development-kqede/).
+
+## See Also
+
+- **[abaplint](/technical/tools/abaplint)** — the tool that performs the rename.
+- **[Builder](/advanced/builds)** — for shipping a custom-namespaced abap2UI5 build.
diff --git a/docs/advanced/rfc.md b/docs/advanced/rfc.md
@@ -37,3 +37,8 @@ You can also use this approach to build a unified Fiori Launchpad that combines:
 - Apps called remotely over RFC from other systems
 
 <img width="700" alt="Centralized Fiori Launchpad combining on-stack and RFC-triggered remote apps" src="https://github.com/user-attachments/assets/a010440d-bd82-46f9-b597-c3ad2273dbde" />
+
+## See Also
+
+- **[The abap2UI5 Architecture](/technical/deep_dive/architecture)** — for context on the generic HTTP service that the RFC connector wraps.
+- **[Use Cases](/get_started/use_cases)** — distributed-system extension scenarios.
diff --git a/docs/advanced/stateful.md b/docs/advanced/stateful.md
@@ -41,3 +41,8 @@ For lighter-weight cases, consider:
 Another option, mostly relevant for legacy stacks: create an infinite session in the backend that holds locks while the UI5 app still communicates statelessly. The session lives in a separate work process and the abap2UI5 frontend talks to it via RFC.
 
 See the [SAP documentation on infinite sessions](https://help.sap.com/docs/ABAP_PLATFORM_NEW/6568469cf5a1460a8d85c58b83d21ec2/47db6c68e4282972e10000000a42189b.html?locale=en-US) and the discussions in [issue #2003](https://github.com/abap2UI5/abap2UI5/issues/2003) and [issue #1971](https://github.com/abap2UI5/abap2UI5/issues/1971) for context.
+
+## See Also
+
+- **[Inside an App → Drafts](/technical/deep_dive/lifecycle#drafts-stateful-feel-stateless-backend)** — how abap2UI5 normally simulates a stateful feel without a stateful backend.
+- **[Glossary → Stateful Session](/technical/glossary#stateful-session)** — quick reference.
diff --git a/docs/technical/cloud.md b/docs/technical/cloud.md
@@ -7,6 +7,8 @@ _Ready for the Future — or Not?_
 
 Whether it's worth building apps with abap2UI5 comes down to future-proofing. In the ABAP ecosystem, this means cloud readiness, closely tied to the ABAP Cloud language version. So what does that mean? And are abap2UI5 apps truly cloud-ready?
 
+This page answers two separate questions: **is the framework cloud-ready** (yes), and **are the apps you build with it cloud-ready** (depends — and this page shows how to make sure they are).
+
 ## What is ABAP Cloud?
 
 ABAP Cloud is a restricted ABAP language version that delivers cloud readiness and upgrade stability. Code that follows the ABAP Cloud rules can run on SAP BTP ABAP Environment and SAP S/4HANA Public Cloud ABAP Environment. SAP guarantees long-term compatibility with future platform updates — with no code changes or extra investment.
diff --git a/docs/technical/concept.md b/docs/technical/concept.md
@@ -7,6 +7,17 @@ _The Architecture of abap2UI5_
 
 This page explains the architectural pattern behind abap2UI5 — HTML Over-the-Wire, applied to UI5 — and why moving UI rendering and app logic to the ABAP backend simplifies development and deployment.
 
+::: tip How to Read the Technical Section
+
+Three reading paths through Technical Insights, depending on what you're after:
+
+- **Just the architecture** — read this page. ~10 min.
+- **The full picture** — this page → [ABAP Thinking, UI5 Results](/technical/dx) → [Cloud Readiness](/technical/cloud) → [Comparisons](/technical/technology/overview). ~30 min.
+- **Implementation deep dive** — start at [Behind the Scenes](/technical/how_it_all_works) and work through the four parts. ~60 min.
+
+New to a term? See the [Glossary](/technical/glossary).
+:::
+
 ## What is HTML Over-the-Wire?
 
 _HTML Over-the-Wire_ describes a server-centric web architecture where the server builds the user interface and sends it to the browser as ready-to-render HTML.
diff --git a/docs/technical/dx.md b/docs/technical/dx.md
@@ -5,7 +5,9 @@ outline: [2, 3]
 
 _A Developer-Centric Approach_
 
-abap2UI5 grew out of the everyday experiences of ABAP developers. It tackles common challenges in development — deployment, caching, debugging, and tooling — while keeping a coding style close to familiar ABAP and SAP GUI patterns like Selection Screens and ALV. The goal: make working with abap2UI5 feel natural to ABAPers. This page looks closely at the main influences behind the framework.
+abap2UI5 grew out of the everyday experiences of ABAP developers. It tackles common challenges in development — deployment, caching, debugging, and tooling — while keeping a coding style close to familiar ABAP and SAP GUI patterns like Selection Screens and ALV. The goal: make working with abap2UI5 feel natural to ABAPers.
+
+This page is the practical counterpart to **[UI5 Over-the-Wire](/technical/concept)**: where that page covers _why_ the architecture is shaped the way it is, this one shows _what daily development feels like_ — comparing classic ABAP patterns to their abap2UI5 counterparts. If you've ever written a `cl_salv_table=>factory(...)` or a `POPUP_TO_CONFIRM`, the parallels here will feel familiar.
 
 ## Simple Output with IF_OO_ADT_CLASSRUN
 
diff --git a/docs/technical/glossary.md b/docs/technical/glossary.md
@@ -0,0 +1,106 @@
+---
+outline: [2, 3]
+---
+# Glossary
+
+Short reference for the terms used across the technical pages. Listed alphabetically.
+
+## ABAP Cloud
+
+A restricted ABAP language version designed for cloud readiness and upgrade stability. Code that follows ABAP Cloud rules runs on SAP BTP ABAP Environment and SAP S/4HANA Public Cloud ABAP Environment. Only released APIs are allowed; classic UI technologies (Web Dynpro, ALV, GUI CFW) and direct database access are excluded. See [Cloud Readiness](/technical/cloud).
+
+## abapGit
+
+Open-source Git client for ABAP. abap2UI5 distributes the framework and apps as abapGit projects so installation is just an abapGit pull — no separate frontend deployment. See the [abapGit page](/technical/tools/abapgit).
+
+## abaplint
+
+Static code analyzer for ABAP. abap2UI5 uses abaplint for code-quality checks **and** for the automatic downport from the main branch (NW 7.50+) to the `702` branch (NW 7.02+). See [abaplint](/technical/tools/abaplint).
+
+## ajson
+
+Open-source ABAP JSON library used by abap2UI5 for all frontend/backend communication. Replaces SAP's `/UI2/CL_JSON` to stay release-independent. See [ajson](/technical/tools/ajson).
+
+## CDS View
+
+Core Data Services view — declarative ABAP-side query definition with optional UI annotations. The backbone of RAP and Fiori Elements. abap2UI5 can SELECT from CDS Views but doesn't depend on them.
+
+## Clean Core
+
+SAP's principle of keeping customer extensions out of the SAP standard objects. Both abap2UI5 and RAP support clean-core extension by relying only on released APIs.
+
+## Draft
+
+A persistence mechanism for interim user state. RAP uses typed draft tables per business object. abap2UI5 uses a single generic draft table (`z2ui5_t_draft`) and serializes the app instance via `if_serializable_object`. See [Inside an App → Drafts](/technical/deep_dive/lifecycle#drafts-stateful-feel-stateless-backend).
+
+## Fiori Elements
+
+UI5 application framework that renders apps from CDS annotations and predefined floorplans (List Report, Object Page, Analytical, …). Part of the RAP stack. See [RAP vs. abap2UI5](/technical/technology/rap).
+
+## Generic HTTP Handler
+
+The single ABAP class that serves every abap2UI5 app. Two strings flow through it: the XML View and the JSON View Model. The handler does not know which app is running — that lives in the user's `z2ui5_if_app` class. See [The abap2UI5 Architecture → The Generic HTTP Handler](/technical/deep_dive/architecture#the-generic-http-handler).
+
+## HDA — Hypermedia-Driven Application
+
+An app where the browser only renders HTML/CSS/JS and never holds the application state. All routing decisions live on the server. abap2UI5's frontend shell behaves as an HDA. See [Foundations → Hypermedia-Driven Apps](/technical/deep_dive/foundations#hypermedia-driven-apps).
+
+## HTML Over the Wire
+
+Server-centric web architecture where the server builds HTML fragments and ships them to the browser, which inserts them into the DOM. The pattern that inspired abap2UI5. Frameworks: htmx, Hotwire, Phoenix LiveView, Laravel Livewire. See [Foundations → HTML Over the Wire](/technical/deep_dive/foundations#html-over-the-wire).
+
+## MPA — Multi-Page Application
+
+Traditional web app where every interaction reloads a full page from the server. ITS Mobile and SAP GUI for HTML are SAP examples.
+
+## OData
+
+REST-based data access protocol used by SAP for client-server communication in UI5 freestyle and RAP. abap2UI5 deliberately does **not** use OData — it sends an XML View and a JSON View Model directly.
+
+## one-code-line
+
+The convention that abap2UI5 keeps a single codebase compatible with both ABAP Cloud and Standard ABAP. abaplint then produces the downport branch automatically. See [Trade-offs → One Code Line](/technical/deep_dive/tradeoffs#one-code-line).
+
+## PAI / PBO
+
+_Process After Input / Process Before Output._ Classic SAP GUI screen lifecycle. abap2UI5's roundtrip model intentionally feels similar — events come in, the backend decides what happens next.
+
+## RAP
+
+_RESTful Application Programming Model._ SAP's standardized framework for cloud-native ABAP applications, built on CDS Views, Behavior Definitions, OData V4, and Fiori Elements UIs. See [RAP vs. abap2UI5](/technical/technology/rap).
+
+## RTTI
+
+_Run Time Type Information / Runtime Type Identification Services._ ABAP API for inspecting and creating types at runtime. abap2UI5 uses RTTI to ship dynamic data models to the frontend (e.g., SE16-style table apps where columns aren't known at design time). See [Defining the Model at Runtime](/technical/deep_dive/architecture#defining-the-model-at-runtime).
+
+## S-RTTI
+
+Open-source extension of standard RTTI. abap2UI5 uses S-RTTI to serialize data references whose types are created at runtime — the standard SAP transformation can't handle that case. See [S-RTTI](/technical/tools/srtti).
+
+## SPA — Single Page Application
+
+Web app where all UI logic lives in JavaScript on the client and the backend only serves data (typically via OData/REST/JSON). Standard UI5 freestyle and RAP/Fiori Elements both follow this model.
+
+## SSR — Server-Side Rendering
+
+Web architecture where the server builds the full HTML document for every page request. Used by ITS, BSP, and Web Dynpro. See [Technology Overview](/technical/technology/overview).
+
+## Stateful Session
+
+A backend session that survives across user interactions, holding work-process state (locks, open cursors, in-memory data). Available for abap2UI5 on private cloud and on-premise systems but not on Public Cloud or BTP. See [Statefulness, Locks](/advanced/stateful).
+
+## UI5 Freestyle
+
+UI5 application built without Fiori Elements — full control over views, controllers, and frontend logic. The browser holds the entire app and fetches data from the backend (typically via OData). See [UI5 Freestyle vs. abap2UI5](/technical/technology/ui5).
+
+## UI5 Over the Wire
+
+The pattern abap2UI5 implements: backend ships the XML View **and** the View Model on every roundtrip; the UI5 frontend shell only renders. The UI5 equivalent of HTML Over the Wire. See [The abap2UI5 Architecture](/technical/deep_dive/architecture).
+
+## XML View
+
+UI5's declarative view definition format. In a normal UI5 app, XML Views live in the frontend project. In abap2UI5, they're built in ABAP via `z2ui5_cl_xml_view` and shipped to the browser on every roundtrip.
+
+## z2ui5_if_app
+
+The single ABAP interface every abap2UI5 app implements. One method (`main`) with one parameter (`client TYPE REF TO z2ui5_if_client`). All app logic lives behind this interface. See [Inside an App](/technical/deep_dive/lifecycle).
diff --git a/docs/technical/technology/overview.md b/docs/technical/technology/overview.md
@@ -6,6 +6,10 @@ _From ITS to abap2UI5_
 
 This page traces the evolution of web development in the ABAP ecosystem — from early server-rendered interfaces like ITS and Web Dynpro to modern client-side SPAs with UI5 Freestyle and RAP — and ends by comparing them to abap2UI5.
 
+The pattern is cyclical: server-rendered (ITS, BSP, Web Dynpro) → client-side SPA (UI5 freestyle, RAP/Fiori Elements) → server-driven again (abap2UI5, "Over the Wire"). Each shift solves real problems with the previous generation. Understanding the cycle makes it easier to decide which tool fits which use case today.
+
+For head-to-head comparisons, see **[RAP vs. abap2UI5](/technical/technology/rap)** and **[UI5 Freestyle vs. abap2UI5](/technical/technology/ui5)**.
+
 ## Internet Transaction Server
 _Bringing SAP GUI to the Web (2000+) (SAP)_
 

Original file line number	Diff line number	Diff line change
`@@ -279,6 +279,7 @@ export default defineConfig({`
`279`	`279`	`{ text: "abapmerge", link: "/technical/tools/abapmerge" },`
`280`	`280`	`],`
`281`	`281`	`},`
	`282`	`+ { text: "Glossary", link: "/technical/glossary" },`
`282`	`283`	`],`
`283`	`284`	`},`
`284`	`285`	`{`