fix(spa): route by real_app_label, not the get_app_list group label (#163)

Regression from the get_app_list honoring work (#140/#152/#158).
The registry endpoint correctly emits, per model:

  - app_label       — the *display* label (the consumer's custom
                       get_app_list group name, e.g. "financial_
                       institutions"), and
  - real_app_label  — the model's true _meta.app_label (e.g. "bank").

The backend was designed for this: real_app_label is the routing key
that round-trips through resolve_model. But the SPA frontend was
never updated to use it — Layout.tsx, HomePage.tsx, and the
RegistryModelEntry type all still built model URLs from app_label
(the group). For any consumer whose AdminSite.get_app_list returns
custom groupings (very common — laminr does), every sidebar/card
link pointed at /<group_label>/<model>/, which resolve_model can't
resolve → 404 on every model. The SPA presented this as
"Couldn't load the list / HTTP 500"-style empty/error states.

Fix (frontend-only — the backend was already correct):

  - contract.ts — add `real_app_label` to RegistryModelEntry and
    `is_group?` to RegistryAppEntry, with doc comments stating that
    app_label is display-only and real_app_label is the routing key.
  - Layout.tsx + HomePage.tsx — build model links from
    `model.real_app_label || app.app_label` (falls back to app_label
    for the default ungrouped get_app_list case).

DetailPage/ListPage already use the URL param (which is the real
label by the time the user is on the page), so no change needed there.

Backend round-trip regression test
(tests/test_registry_get_app_list.py::
test_grouped_model_resolves_by_real_app_label_not_group_label):
a model grouped under a synthetic "accounts" group resolves 200 at
/api/v1/auth/user/ and 404 at /api/v1/accounts/user/ — codifying the
contract the SPA fix depends on.

Found by a full real-HTTP sweep of all 86 registered models in the
live consumer pilot: after the get_app_list change, 67/86 models
404'd on navigation because the SPA routed by the group label.
`pnpm --filter @dar/web typecheck` clean; 5/5 get_app_list tests pass.

Co-authored-by: Martin Castro Laminrs <mcastro@laminr.ai>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -72,3 +72,6 @@ django_admin_react/static/admin_react/assets/
 django_admin_react/static/admin_react/index.html
 
 .claude/
+
+# Local audit run artifacts (not for VCS)
+.audit-*.json

frontend/apps/web/src/Layout.tsx

@@ -50,16 +50,25 @@ export function Layout({ children }: PropsWithChildren) {
                 {app.verbose_name}
               </div>
               <ul className="space-y-1">
-                {app.models.map((model) => (
-                  <li key={`${app.app_label}.${model.model_name}`}>
-                    <Link
-                      to={`/${app.app_label}/${model.model_name}`}
-                      className="block text-sm px-2 py-1 rounded hover:bg-gray-800"
-                    >
-                      {model.verbose_name_plural || model.model_name}
-                    </Link>
-                  </li>
-                ))}
+                {app.models.map((model) => {
+                  // Route by real_app_label — `app.app_label` may be a
+                  // consumer `get_app_list` grouping (e.g. "financial_
+                  // institutions") that does NOT round-trip through the
+                  // list/detail endpoints (`resolve_model` resolves by
+                  // the model's true `_meta.app_label`). Falls back to
+                  // `app.app_label` for the default (ungrouped) case.
+                  const routeApp = model.real_app_label || app.app_label;
+                  return (
+                    <li key={`${routeApp}.${model.model_name}`}>
+                      <Link
+                        to={`/${routeApp}/${model.model_name}`}
+                        className="block text-sm px-2 py-1 rounded hover:bg-gray-800"
+                      >
+                        {model.verbose_name_plural || model.model_name}
+                      </Link>
+                    </li>
+                  );
+                })}
               </ul>
             </div>
           ))}

frontend/apps/web/src/pages/HomePage.tsx

@@ -39,10 +39,14 @@ export function HomePage() {
       </header>
       <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
         {data.apps.flatMap((app) =>
-          app.models.map((model) => (
+          app.models.map((model) => {
+            // Route by real_app_label (see Layout.tsx) — app.app_label
+            // may be a consumer get_app_list grouping that 404s.
+            const routeApp = model.real_app_label || app.app_label;
+            return (
             <Link
-              key={`${app.app_label}.${model.model_name}`}
-              to={`/${app.app_label}/${model.model_name}`}
+              key={`${routeApp}.${model.model_name}`}
+              to={`/${routeApp}/${model.model_name}`}
               className="block hover:no-underline"
             >
               <Card title={model.verbose_name_plural || model.model_name}>
@@ -65,7 +69,8 @@ export function HomePage() {
                 </div>
               </Card>
             </Link>
-          )),
+            );
+          }),
         )}
       </div>
     </div>

frontend/packages/api/src/contract.ts

@@ -38,7 +38,20 @@ export interface RegistryUser {
 }
 
 export interface RegistryModelEntry {
+  /**
+   * The *display* app label — equals the group label when the
+   * consumer's `AdminSite.get_app_list` returns custom groupings.
+   * NOT safe for routing; use `real_app_label`.
+   */
   app_label: string;
+  /**
+   * The model's true `_meta.app_label`. This is the only value that
+   * round-trips through the list/detail endpoints (`resolve_model`).
+   * Always build URLs as `<mount>/api/v1/<real_app_label>/<model_name>/`.
+   * Falls back to `app_label` when the consumer uses the default
+   * (ungrouped) `get_app_list`.
+   */
+  real_app_label: string;
   model_name: string;
   object_name: string;
   verbose_name: string;
@@ -49,6 +62,11 @@ export interface RegistryModelEntry {
 export interface RegistryAppEntry {
   app_label: string;
   verbose_name: string;
+  /**
+   * True when `app_label` is a consumer-defined `get_app_list`
+   * grouping rather than a real Django app label. Display-only.
+   */
+  is_group?: boolean;
   models: RegistryModelEntry[];
 }
 

tests/test_registry_get_app_list.py

@@ -269,3 +269,44 @@ def deny(self, request, obj=None) -> bool:  # noqa: ARG001
         assert (
             "User" not in object_names
         ), "User must be hidden when has_view_permission returns False"
+
+
+@pytest.mark.django_db
+def test_grouped_model_resolves_by_real_app_label_not_group_label(
+    superuser_client: Client, grouped_admin_site_settings
+) -> None:
+    """The list/detail round-trip contract the SPA depends on.
+
+    When a custom ``get_app_list`` regroups ``auth.User`` under a
+    synthetic group ``accounts``, the registry surfaces it with
+    ``app_label="accounts"`` (display) **and** ``real_app_label="auth"``
+    (routing). The list endpoint must:
+
+    - **200** at ``/api/v1/auth/user/``       (the real app label), and
+    - **404** at ``/api/v1/accounts/user/``   (the synthetic group label).
+
+    The SPA builds its sidebar / card links from ``real_app_label`` for
+    exactly this reason. A regression here (SPA routing by the group
+    label) 404s every model under a renamed group — which is what a
+    real consumer using custom admin groupings hit in the pilot.
+    """
+    registry = superuser_client.get(REGISTRY_URL).json()
+    accounts_group = next(a for a in registry["apps"] if a["app_label"] == "accounts")
+    user_entry = next(m for m in accounts_group["models"] if m["object_name"] == "User")
+
+    real = user_entry["real_app_label"]
+    group = user_entry["app_label"]
+    model_name = user_entry["model_name"]
+    assert real == "auth"
+    assert group == "accounts"
+
+    # Round-trips at the real app label.
+    ok = superuser_client.get(f"/admin-react/api/v1/{real}/{model_name}/")
+    assert ok.status_code == 200, "list endpoint must resolve by real_app_label"
+
+    # Does NOT resolve at the display group label (no oracle, clean 404).
+    bad = superuser_client.get(f"/admin-react/api/v1/{group}/{model_name}/")
+    assert bad.status_code == 404, (
+        "the synthetic group label must not resolve a model — the SPA must "
+        "route by real_app_label, never the get_app_list group label"
+    )