From 23ee1377e3cfeeb2ff80a3285d8eafd978a91ff7 Mon Sep 17 00:00:00 2001
From: Adam Haeger <adamgullerud@gmail.com>
Date: Tue, 23 Sep 2025 10:39:26 +0200
Subject: [PATCH 1/5] ADR created

---
 adr/002-backend-data-initialization.md | 187 +++++++++++++++++++++++++
 1 file changed, 187 insertions(+)
 create mode 100644 adr/002-backend-data-initialization.md

diff --git a/adr/002-backend-data-initialization.md b/adr/002-backend-data-initialization.md
new file mode 100644
index 0000000000..55b4841c7b
--- /dev/null
+++ b/adr/002-backend-data-initialization.md
@@ -0,0 +1,187 @@
+# ADR: Move most initial data loading to app-backend
+
+- **Status:** Proposed
+- **Date:** 2025-09-23
+- **Owner:** Team Studio
+- **Related:** Altinn/altinn-studio#16309 (Epic) ([GitHub][1])
+
+## Context
+
+Today `app-frontend` bootstraps by mounting a stack of query providers (TanStack Query), each fetching pieces of application/instance/party/config data on load. This creates:
+
+- Many requests and duplicated invalidation logic
+- Complex provider/effect nesting and brittle boot order
+- Longer TTFB/TTI and heavier cognitive load for app developers
+
+Epic #16309 proposes shifting _initial_ data orchestration to `app-backend` and delivering a consolidated payload to the client at bootstrap, reducing round trips and complexity. ([GitHub][1])
+
+## Decision
+
+We will:
+
+1. **Generate the bootstrap HTML in `HomeController` (app-backend).**
+   Backend takes ownership of serving the app shell (replaces handcrafted Index.cshtml). ([GitHub][1])
+2. **Adopt path-based routing (no `HashRouter`).**
+   Backend resolves/serves deep links, delegating route rendering to `app-frontend`. Back-compat preserved for legacy hash URLs (see Rollout). ([GitHub][1])
+3. **Embed immutable “AppData” in the HTML.**
+   Static, versionable, cross-variant data is serialized into a global (e.g., `window.AltinnAppData = {...}`) in the bootstrap page. ([GitHub][1])
+4. **Provide an “InitialInstanceData” bundle when opening an existing instance.**
+   When backend detects an instance context, it embeds (or exposes via single endpoint) the static-at-boot instance data adjacent to `AppData`, so the client does not immediately refetch/invalidate. Further interactions use targeted APIs. ([GitHub][1])
+5. **Remove RuleHandler/RuleConfiguration in this major.**
+   Do not migrate them to the new boot flow (handled by separate task). ([GitHub][1])
+
+In scope: catalog and migrate all initial queries across stateless, stateless-anon, and stateful apps. Out of scope: data that must be updated _after_ boot. ([GitHub][1])
+
+```mermaid
+graph LR
+A[User's Browser]:::actor
+
+subgraph S1["Before — frontend orchestrates boot"]
+A --> FFE[app-frontend]
+FFE -->|fetch on mount| Q1[GET /texts]
+FFE -->|fetch on mount| Q2[GET /app-metadata]
+FFE -->|fetch on mount| Q3[GET /profile/party]
+FFE -->|fetch on mount| Q4[GET /instances?active=true]
+FFE -->|fetch on mount| Q5[GET /orgs]
+FFE -->|fetch on mount| Q6[GET /ui-config]
+FFE -.-> FX[Complex provider/effect graph]
+end
+
+subgraph S2["After — backend assembles initial payload"]
+A --> BE[app-backend HomeController]
+BE -->|orchestrates| P1[(Platform APIs)]
+P1 --> BE
+BE -->|Bootstrap HTML + AppData + InitialInstanceData| A
+A --> FFE2[app-frontend hydrate & render]
+FFE2 -->|seed query cache| QC[Dehydrated caches]
+FFE2 -->|targeted fetch on demand| P2[(Platform APIs)]
+end
+
+subgraph R["Routing change"]
+H1[Legacy hash routes] -->|301/compat| PATH[Path-based URLs]
+end
+
+classDef actor fill:#eef,stroke:#77f,color:#000
+```
+
+## Rationale
+
+- **Performance:** Fewer requests and no waterfall; better TTFB/TTI by shipping what the app needs up front.
+- **Simplicity:** One place orchestrates initial data; frontend boot becomes deterministic.
+- **Reliability:** Backend can decide what to load based on route/instance/party and enforce pagination/limits.
+- **Security:** Backend can apply authz, shape data, and set cache headers consistently before client executes.
+
+## Considered Options
+
+1. **Status quo (frontend-orchestrated queries).**
+   Rejected: retains complexity and network overhead.
+2. **SSR/streaming React for all routes.**
+   Rejected for now: higher cost/risk; we only need consolidated data at boot, not full SSR.
+3. **Bulk endpoints.**
+   Rejected: increases backend complexity without clear benefit vs app-backend controller.
+
+## Technical Notes (non-normative)
+
+- **Bootstrap contract**
+
+  ```html
+  <script
+    id="__appdata"
+    type="application/json"
+  >
+    { ... AppData ... }
+  </script>
+  <script
+    id="__initialInstanceData"
+    type="application/json"
+  >
+    { ... } <!-- present only when opening an instance -->
+  </script>
+  <script>
+    window.AltinnAppData = JSON.parse(document.getElementById('__appdata').textContent);
+  </script>
+  <script>
+    window.AltinnInitialInstanceData = JSON.parse(
+      document.getElementById('__initialInstanceData')?.textContent || 'null',
+    );
+  </script>
+  ```
+
+  Prefer `<script type="application/json">` nodes over inline JS to simplify CSP. Add a nonce for any inline scripts if needed.
+
+- **Caching:**
+  - `AppData`: strong ETag keyed by app version/build hash; `Cache-Control: public, max-age=0, must-revalidate`.
+  - Instance bundle: `no-store` or short max-age; includes stable pagination cursors if applicable.
+
+- **Routing:**
+  - Backend maps `/` `/instances/:id/*` `/tasks/:taskId` etc. to a single `HomeController` action that embeds the correct initial payload and serves static assets.
+  - Legacy `/#/...` routes: 301 to new path form; preserve query and fragment where safe.
+
+- **Frontend boot:**
+  - Replace nested providers with a single `BootContext` that hydrates from embedded JSON.
+  - TanStack Query seeds caches with `dehydrate(...)` from embedded objects to avoid first paint refetch.
+
+- **Pagination upgrades:**
+  - Add pagination on _active instances_ and _parties_ APIs as specified in tasks. Cursor-based preferred. ([GitHub][1])
+
+## Consequences
+
+**Positive**
+
+- Fewer network round trips at boot; smaller provider graph in UI.
+- Clearer ownership boundaries: backend decides _what_; frontend renders _how_.
+- Easier to test: snapshot input JSON → deterministic initial UI.
+
+**Negative / Trade-offs**
+
+- Slightly more logic in backend (must maintain schema for `AppData`/`InitialInstanceData`).
+- Coordinated deploys required when the bootstrap contract changes.
+- Initial HTML grows; ensure gzip/brotli and avoid embedding large option lists—keep those via APIs.
+
+## Security & Compliance
+
+- Enforce CSP with nonces; no unsafe-inline.
+- Ensure embedded data contains only what the current principal may see.
+- PII in instance payload must _not_ be cacheable by intermediaries (`private, no-store`).
+- Log correlation ids for all preloads.
+
+## Rollout Plan
+
+1. **Behind feature flag** in app-backend and app-frontend.
+2. **Dual-boot phase:** serve embedded payload but keep existing client queries as fallback; add telemetry comparing both.
+3. **Route migration:** enable path-based routing; ship redirects for legacy hash URLs; validate deep links.
+4. **Delete old providers/effects** and RuleHandler/RuleConfiguration.
+5. **Docs & templates:** update app templates and docs; provide migration guide for app owners.
+
+## Impacted Areas
+
+- `app-backend`: `HomeController`, payload assemblers, auth.
+- `app-frontend`: routing, bootstrapping, query seeding, removal of nested providers.
+- APIs: instances list, parties list (add pagination). ([GitHub][1])
+
+## Open Questions
+
+- Precise schema boundaries for `AppData` vs `InitialInstanceData`.
+- Which option sources (datalists) are always API-fetched vs allowed to be embedded for tiny lists? (Epic notes say datalist+options stay API. Confirm.) ([GitHub][1])
+- CSP strategy: JSON script tags vs inline assignment with nonce—prefer JSON tags.
+- Error UX if embedded payload fails to parse (serve minimal shell with error boundary?).
+
+## Migration Guide (high level)
+
+- Stop reading boot-critical data via effects/providers.
+- Read from `window.AltinnAppData` / `window.AltinnInitialInstanceData` (or JSON script tags).
+- Pre-seed TanStack Query caches using embedded payload; keep mutations/targeted fetches unchanged.
+- Replace hash routes with path routes; verify deep links and bookmarking.
+- Remove RuleHandler/RuleConfiguration references.
+
+## Acceptance Criteria
+
+- Boot of stateless and stateful apps requires ≤ 2 requests (HTML + assets) before first interactive paint (excluding datalist/options APIs).
+- No client refetch for data already embedded at boot.
+- Path URLs work for all previously supported deep links; legacy hashes redirect.
+- Parties/instances APIs expose tested pagination; UI consumes it.
+- RuleHandler/RuleConfiguration removed from templates and docs.
+
+**Sources:** Epic details and tasks from Altinn/altinn-studio issue #16309. ([GitHub][1])
+
+[1]: https://github.com/Altinn/altinn-studio/issues/16309 'Move most initial data loading to app-backend · Issue #16309 · Altinn/altinn-studio · GitHub'

From ace1828461da1266db4e90efdfdad54ed88cb0a2 Mon Sep 17 00:00:00 2001
From: Adam Haeger <adamgullerud@gmail.com>
Date: Tue, 23 Sep 2025 10:46:11 +0200
Subject: [PATCH 2/5] update

---
 adr/002-backend-data-initialization.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/adr/002-backend-data-initialization.md b/adr/002-backend-data-initialization.md
index 55b4841c7b..d4bcd6a181 100644
--- a/adr/002-backend-data-initialization.md
+++ b/adr/002-backend-data-initialization.md
@@ -20,17 +20,17 @@ Epic #16309 proposes shifting _initial_ data orchestration to `app-backend` and
 We will:
 
 1. **Generate the bootstrap HTML in `HomeController` (app-backend).**
-   Backend takes ownership of serving the app shell (replaces handcrafted Index.cshtml). ([GitHub][1])
+   Backend takes ownership of serving the app shell (replaces handcrafted Index.cshtml).
 2. **Adopt path-based routing (no `HashRouter`).**
-   Backend resolves/serves deep links, delegating route rendering to `app-frontend`. Back-compat preserved for legacy hash URLs (see Rollout). ([GitHub][1])
+   Backend resolves/serves deep links, delegating route rendering to `app-frontend`. Back-compat preserved for legacy hash URLs (see Rollout).
 3. **Embed immutable “AppData” in the HTML.**
-   Static, versionable, cross-variant data is serialized into a global (e.g., `window.AltinnAppData = {...}`) in the bootstrap page. ([GitHub][1])
+   Static, versionable, cross-variant data is serialized into a global (e.g., `window.AltinnAppData = {...}`) in the bootstrap page.
 4. **Provide an “InitialInstanceData” bundle when opening an existing instance.**
    When backend detects an instance context, it embeds (or exposes via single endpoint) the static-at-boot instance data adjacent to `AppData`, so the client does not immediately refetch/invalidate. Further interactions use targeted APIs. ([GitHub][1])
 5. **Remove RuleHandler/RuleConfiguration in this major.**
-   Do not migrate them to the new boot flow (handled by separate task). ([GitHub][1])
+   Do not migrate them to the new boot flow (handled by separate task).
 
-In scope: catalog and migrate all initial queries across stateless, stateless-anon, and stateful apps. Out of scope: data that must be updated _after_ boot. ([GitHub][1])
+In scope: catalog and migrate all initial queries across stateless, stateless-anon, and stateful apps. Out of scope: data that must be updated _after_ boot.
 
 ```mermaid
 graph LR
@@ -122,7 +122,7 @@ classDef actor fill:#eef,stroke:#77f,color:#000
   - TanStack Query seeds caches with `dehydrate(...)` from embedded objects to avoid first paint refetch.
 
 - **Pagination upgrades:**
-  - Add pagination on _active instances_ and _parties_ APIs as specified in tasks. Cursor-based preferred. ([GitHub][1])
+  - Add pagination on _active instances_ and _parties_ APIs as specified in tasks. Cursor-based preferred.
 
 ## Consequences
 
@@ -143,7 +143,6 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 - Enforce CSP with nonces; no unsafe-inline.
 - Ensure embedded data contains only what the current principal may see.
 - PII in instance payload must _not_ be cacheable by intermediaries (`private, no-store`).
-- Log correlation ids for all preloads.
 
 ## Rollout Plan
 
@@ -157,12 +156,12 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 
 - `app-backend`: `HomeController`, payload assemblers, auth.
 - `app-frontend`: routing, bootstrapping, query seeding, removal of nested providers.
-- APIs: instances list, parties list (add pagination). ([GitHub][1])
+- APIs: instances list, parties list (add pagination).
 
 ## Open Questions
 
 - Precise schema boundaries for `AppData` vs `InitialInstanceData`.
-- Which option sources (datalists) are always API-fetched vs allowed to be embedded for tiny lists? (Epic notes say datalist+options stay API. Confirm.) ([GitHub][1])
+- Which option sources (datalists) are always API-fetched vs allowed to be embedded for tiny lists? (Epic notes say datalist+options stay API. Confirm.)
 - CSP strategy: JSON script tags vs inline assignment with nonce—prefer JSON tags.
 - Error UX if embedded payload fails to parse (serve minimal shell with error boundary?).
 

From 4cdb03cb35ba272dfd3f87c9690df47ffc17e6c0 Mon Sep 17 00:00:00 2001
From: Adam Haeger <adamgullerud@gmail.com>
Date: Tue, 23 Sep 2025 12:27:00 +0200
Subject: [PATCH 3/5] update after feedback

---
 adr/002-backend-data-initialization.md | 48 +++++---------------------
 1 file changed, 9 insertions(+), 39 deletions(-)

diff --git a/adr/002-backend-data-initialization.md b/adr/002-backend-data-initialization.md
index d4bcd6a181..43f0f913b4 100644
--- a/adr/002-backend-data-initialization.md
+++ b/adr/002-backend-data-initialization.md
@@ -22,7 +22,7 @@ We will:
 1. **Generate the bootstrap HTML in `HomeController` (app-backend).**
    Backend takes ownership of serving the app shell (replaces handcrafted Index.cshtml).
 2. **Adopt path-based routing (no `HashRouter`).**
-   Backend resolves/serves deep links, delegating route rendering to `app-frontend`. Back-compat preserved for legacy hash URLs (see Rollout).
+   Backend resolves/serves deep links, delegating route rendering to `app-frontend`. Back-compat preserved for legacy hash URLs.
 3. **Embed immutable “AppData” in the HTML.**
    Static, versionable, cross-variant data is serialized into a global (e.g., `window.AltinnAppData = {...}`) in the bootstrap page.
 4. **Provide an “InitialInstanceData” bundle when opening an existing instance.**
@@ -53,14 +53,10 @@ BE -->|orchestrates| P1[(Platform APIs)]
 P1 --> BE
 BE -->|Bootstrap HTML + AppData + InitialInstanceData| A
 A --> FFE2[app-frontend hydrate & render]
-FFE2 -->|seed query cache| QC[Dehydrated caches]
+FFE2 -->|reads global variable| QC[global state variables]
 FFE2 -->|targeted fetch on demand| P2[(Platform APIs)]
 end
 
-subgraph R["Routing change"]
-H1[Legacy hash routes] -->|301/compat| PATH[Path-based URLs]
-end
-
 classDef actor fill:#eef,stroke:#77f,color:#000
 ```
 
@@ -69,15 +65,12 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 - **Performance:** Fewer requests and no waterfall; better TTFB/TTI by shipping what the app needs up front.
 - **Simplicity:** One place orchestrates initial data; frontend boot becomes deterministic.
 - **Reliability:** Backend can decide what to load based on route/instance/party and enforce pagination/limits.
-- **Security:** Backend can apply authz, shape data, and set cache headers consistently before client executes.
 
 ## Considered Options
 
 1. **Status quo (frontend-orchestrated queries).**
    Rejected: retains complexity and network overhead.
-2. **SSR/streaming React for all routes.**
-   Rejected for now: higher cost/risk; we only need consolidated data at boot, not full SSR.
-3. **Bulk endpoints.**
+   2**Bulk endpoints.**
    Rejected: increases backend complexity without clear benefit vs app-backend controller.
 
 ## Technical Notes (non-normative)
@@ -107,19 +100,9 @@ classDef actor fill:#eef,stroke:#77f,color:#000
   </script>
   ```
 
-  Prefer `<script type="application/json">` nodes over inline JS to simplify CSP. Add a nonce for any inline scripts if needed.
-
-- **Caching:**
-  - `AppData`: strong ETag keyed by app version/build hash; `Cache-Control: public, max-age=0, must-revalidate`.
-  - Instance bundle: `no-store` or short max-age; includes stable pagination cursors if applicable.
-
 - **Routing:**
   - Backend maps `/` `/instances/:id/*` `/tasks/:taskId` etc. to a single `HomeController` action that embeds the correct initial payload and serves static assets.
-  - Legacy `/#/...` routes: 301 to new path form; preserve query and fragment where safe.
-
-- **Frontend boot:**
-  - Replace nested providers with a single `BootContext` that hydrates from embedded JSON.
-  - TanStack Query seeds caches with `dehydrate(...)` from embedded objects to avoid first paint refetch.
+  - Legacy `/#/...` routes: frontend redirects to updated routes.
 
 - **Pagination upgrades:**
   - Add pagination on _active instances_ and _parties_ APIs as specified in tasks. Cursor-based preferred.
@@ -140,39 +123,26 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 
 ## Security & Compliance
 
-- Enforce CSP with nonces; no unsafe-inline.
 - Ensure embedded data contains only what the current principal may see.
-- PII in instance payload must _not_ be cacheable by intermediaries (`private, no-store`).
 
 ## Rollout Plan
 
-1. **Behind feature flag** in app-backend and app-frontend.
-2. **Dual-boot phase:** serve embedded payload but keep existing client queries as fallback; add telemetry comparing both.
-3. **Route migration:** enable path-based routing; ship redirects for legacy hash URLs; validate deep links.
-4. **Delete old providers/effects** and RuleHandler/RuleConfiguration.
-5. **Docs & templates:** update app templates and docs; provide migration guide for app owners.
+1**Route migration:** enable path-based routing; ship redirects for legacy hash URLs; validate deep links.
+2**Delete old providers/effects** and RuleHandler/RuleConfiguration.
+3**Docs & templates:** update app templates and docs; provide migration guide for app owners.
 
 ## Impacted Areas
 
 - `app-backend`: `HomeController`, payload assemblers, auth.
-- `app-frontend`: routing, bootstrapping, query seeding, removal of nested providers.
+- `app-frontend`: routing, bootstrapping, removal of nested providers.
 - APIs: instances list, parties list (add pagination).
+- `app-template`: must be updated to support new loading.
 
 ## Open Questions
 
-- Precise schema boundaries for `AppData` vs `InitialInstanceData`.
 - Which option sources (datalists) are always API-fetched vs allowed to be embedded for tiny lists? (Epic notes say datalist+options stay API. Confirm.)
-- CSP strategy: JSON script tags vs inline assignment with nonce—prefer JSON tags.
 - Error UX if embedded payload fails to parse (serve minimal shell with error boundary?).
 
-## Migration Guide (high level)
-
-- Stop reading boot-critical data via effects/providers.
-- Read from `window.AltinnAppData` / `window.AltinnInitialInstanceData` (or JSON script tags).
-- Pre-seed TanStack Query caches using embedded payload; keep mutations/targeted fetches unchanged.
-- Replace hash routes with path routes; verify deep links and bookmarking.
-- Remove RuleHandler/RuleConfiguration references.
-
 ## Acceptance Criteria
 
 - Boot of stateless and stateful apps requires ≤ 2 requests (HTML + assets) before first interactive paint (excluding datalist/options APIs).

From 897fea7766323588783178c0bb6c7143cc15358f Mon Sep 17 00:00:00 2001
From: Adam Haeger <adamgullerud@gmail.com>
Date: Tue, 23 Sep 2025 12:28:28 +0200
Subject: [PATCH 4/5] update after feedback

---
 adr/002-backend-data-initialization.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/adr/002-backend-data-initialization.md b/adr/002-backend-data-initialization.md
index 43f0f913b4..3f60b91866 100644
--- a/adr/002-backend-data-initialization.md
+++ b/adr/002-backend-data-initialization.md
@@ -70,7 +70,7 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 
 1. **Status quo (frontend-orchestrated queries).**
    Rejected: retains complexity and network overhead.
-   2**Bulk endpoints.**
+2. **Bulk endpoints.**
    Rejected: increases backend complexity without clear benefit vs app-backend controller.
 
 ## Technical Notes (non-normative)

From 46a29c21f54201c1c7d5c68be08a900b6b302b5d Mon Sep 17 00:00:00 2001
From: Adam Haeger <adamgullerud@gmail.com>
Date: Tue, 23 Sep 2025 12:41:43 +0200
Subject: [PATCH 5/5] update

---
 adr/002-backend-data-initialization.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/adr/002-backend-data-initialization.md b/adr/002-backend-data-initialization.md
index 3f60b91866..6900e8d2b0 100644
--- a/adr/002-backend-data-initialization.md
+++ b/adr/002-backend-data-initialization.md
@@ -142,6 +142,7 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 
 - Which option sources (datalists) are always API-fetched vs allowed to be embedded for tiny lists? (Epic notes say datalist+options stay API. Confirm.)
 - Error UX if embedded payload fails to parse (serve minimal shell with error boundary?).
+- What consequences does removing index.cshtml have and how should we support existing modifications that apps have implemented?
 
 ## Acceptance Criteria
 
@@ -149,7 +150,7 @@ classDef actor fill:#eef,stroke:#77f,color:#000
 - No client refetch for data already embedded at boot.
 - Path URLs work for all previously supported deep links; legacy hashes redirect.
 - Parties/instances APIs expose tested pagination; UI consumes it.
-- RuleHandler/RuleConfiguration removed from templates and docs.
+- Update RuleHandler/RuleConfiguration to mention that this functionality will be removed in future versions.
 
 **Sources:** Epic details and tasks from Altinn/altinn-studio issue #16309. ([GitHub][1])