Archipelago — open-source initial import
This commit is contained in:
Archipelago
@@ -0,0 +1,322 @@
|
||||
# Phase 2: UI Performance - Pattern Map
|
||||
|
||||
**Mapped:** 2026-07-30
|
||||
**Files analyzed:** 9 (new/modified)
|
||||
**Analogs found:** 9 / 9 (all analogs are in-repo; several files ARE their own analog — modify-in-place)
|
||||
|
||||
## File Classification
|
||||
|
||||
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
||||
|--------------------|------|-----------|-----------------|----------------|
|
||||
| `neode-ui/src/views/Dashboard.vue` (nested RouterView, ~line 87) | route/container (KeepAlive host) | request-response (render orchestration) | itself (template restructure) — pattern source: Vue Router 4 `v-slot` docs example | exact-pattern, no in-repo KeepAlive precedent |
|
||||
| `neode-ui/src/composables/useCachedResource.ts` | composable (SWR hook) | CRUD (cache read/refresh) | itself — extend with `onActivated` | exact (self-modify) |
|
||||
| `neode-ui/src/views/dashboard/useRouteTransitions.ts` | utility (route classification) | transform | itself — `isDetailRoute`/`TAB_ORDER` extended into an explicit main-tab-name list | exact (self-modify) |
|
||||
| `.planning/phases/02-ui-performance/02-FINDINGS.md` (new, D-10 deliverable) | doc/config | batch (one-time profiling report) | no code analog — doc-only deliverable | n/a |
|
||||
| `neode-ui/src/views/Apps.vue`, `Mesh.vue`, `Cloud.vue`, `Server.vue`, `web5/Web5.vue`, marketplace/discover view (candidates, D-02-gated) | component (main-tab view) | request-response + CRUD (fetch-on-mount → converted to SWR) | `neode-ui/src/views/Cloud.vue` (already partially on `useCachedResource`) | role-match, best-in-class |
|
||||
| `neode-ui/src/views/ContainerAppDetails.vue` (`onMounted`, lines 169-172) | component (secondary screen) | request-response (serial waterfall → parallel) | itself — Pattern 3 fix in place | exact (self-modify) |
|
||||
| `neode-ui/src/views/AppDetails.vue` and other secondary screens (D-04 candidates) | component (secondary screen) | CRUD (keyed cache, no KeepAlive) | `neode-ui/src/views/Cloud.vue`'s `peersResource`/`countsResource` usage | role-match |
|
||||
| `neode-ui/src/views/Chat.vue` (`aiuiUrl` computed, lines 74-82) | component (iframe URL builder) | transform (query-param construction) | itself — extend query string for D-14 | exact (self-modify) |
|
||||
| `neode-ui/src/stores/resources.ts` | store | CRUD (cache backing store) | itself — unchanged, referenced only | n/a (no changes expected) |
|
||||
|
||||
## Pattern Assignments
|
||||
|
||||
### `neode-ui/src/views/Dashboard.vue` (route/container, KeepAlive host)
|
||||
|
||||
**Analog:** No in-repo KeepAlive precedent exists (`grep -r "KeepAlive" neode-ui/src` returns nothing) — the pattern to introduce is a Vue Router 4 official pattern, applied to this file's own existing nested `<RouterView>` structure.
|
||||
|
||||
**Current structure to modify** (`neode-ui/src/views/Dashboard.vue:87-118`):
|
||||
```vue
|
||||
<RouterView v-slot="{ Component, route }">
|
||||
<Transition :name="getTransitionName(route)">
|
||||
<div :key="route.path" class="view-wrapper">
|
||||
<div v-if="route.path === '/dashboard/chat' || route.path === '/dashboard/mesh'" ...>
|
||||
<component :is="Component" />
|
||||
</div>
|
||||
<div v-else ...>
|
||||
<component :is="Component" class="view-container flex-none" />
|
||||
<div class="shrink-0 h-6 md:h-12" aria-hidden="true"></div>
|
||||
</div>
|
||||
</div>
|
||||
</Transition>
|
||||
</RouterView>
|
||||
```
|
||||
Two branches both wrap `<component :is="Component" />` — `<KeepAlive>` must be inserted around `<component :is="Component" />` in BOTH branches (or the two wrapper `<div>`s must be unified behind a single KeepAlive so classes/padding still differ per route). The `:key="route.path"` is currently on the outer wrapper `<div>`, not on `<component>` itself — leave it there (it only drives the `<Transition>`, not KeepAlive's cache identity) per RESEARCH.md's note that keying `<component>` by `route.path` is only a footgun for *varying-param* detail routes, which are excluded from KeepAlive entirely (D-04).
|
||||
|
||||
**Target pattern** (Vue Router 4 official form, RESEARCH.md Pattern 1):
|
||||
```vue
|
||||
<router-view v-slot="{ Component, route }">
|
||||
<transition :name="transitionName">
|
||||
<keep-alive :include="mainTabComponentNames" :max="8">
|
||||
<component :is="Component" :key="route.path" />
|
||||
</keep-alive>
|
||||
</transition>
|
||||
</router-view>
|
||||
```
|
||||
`mainTabComponentNames` should be built explicitly from the `TAB_ORDER` main-tab set in `useRouteTransitions.ts` (Home, Apps, Mesh, Cloud, Server, Web5, Marketplace/Discover, Chat, Settings, Fleet) — NOT derived from `isDetailRoute()` (Pitfall 7: that helper under-covers secondary screens like `cloud/:folderId`, `server/openwrt`, `web5/credentials`, etc.).
|
||||
|
||||
**Fallback if `include`/`exclude` name-matching misbehaves** (Pitfall 1 — confirm via manual smoke test first): drop `include` entirely and rely on `:max="8"` alone with LRU eviction (documented as working correctly with async components even when `include`/`exclude` name-matching does not).
|
||||
|
||||
---
|
||||
|
||||
### `neode-ui/src/composables/useCachedResource.ts` (composable, self-modify)
|
||||
|
||||
**Analog:** itself (full file already read, 107 lines — no re-read needed)
|
||||
|
||||
**Current imports** (lines 25-26):
|
||||
```typescript
|
||||
import { computed, getCurrentScope, onScopeDispose, type ComputedRef } from 'vue'
|
||||
import { useResourcesStore, type ResourceEntry, type ResourceLoadState } from '@/stores/resources'
|
||||
```
|
||||
|
||||
**Existing lifecycle-scope pattern to mirror** (lines 84-94):
|
||||
```typescript
|
||||
if (getCurrentScope()) {
|
||||
onScopeDispose(() => {
|
||||
unsubscribe()
|
||||
window.removeEventListener('focus', onFocus)
|
||||
aborter.abort()
|
||||
})
|
||||
}
|
||||
|
||||
if (opts.immediate ?? true) refreshIfStale()
|
||||
```
|
||||
|
||||
**Required addition** (Pattern 2, RESEARCH.md) — add alongside the `onScopeDispose` block:
|
||||
```typescript
|
||||
import { onActivated } from 'vue'
|
||||
// ...
|
||||
if (getCurrentScope()) {
|
||||
onActivated(() => refreshIfStale())
|
||||
}
|
||||
```
|
||||
Safe unconditionally — Vue no-ops `onActivated` outside a `<KeepAlive>` boundary, so this benefits main tabs (real fix) and secondary screens (harmless no-op) with one shared change. `refreshIfStale()` (lines 71-74) and `stale()` are already defined and reusable as-is — no new staleness logic needed.
|
||||
|
||||
---
|
||||
|
||||
### `neode-ui/src/views/dashboard/useRouteTransitions.ts` (utility, self-modify)
|
||||
|
||||
**Analog:** itself (full 183 lines read)
|
||||
|
||||
**Existing (insufficient) classification helper** (lines 38-41):
|
||||
```typescript
|
||||
export function isDetailRoute(path: string): boolean {
|
||||
return (path.includes('/apps/') && !path.endsWith('/apps')) ||
|
||||
(path.includes('/marketplace/') && !path.endsWith('/marketplace'))
|
||||
}
|
||||
```
|
||||
Do NOT reuse this as the KeepAlive `include` source (Pitfall 7 — misses `cloud/:folderId`, `server/openwrt`, `web5/credentials`, `goals/:goalId`, `app-session/:appId`, `web5/networking-profits`, `apps/lnd/channels`). Instead build the KeepAlive include list from `TAB_ORDER` (lines 4-15), which already enumerates exactly the main-tab paths:
|
||||
```typescript
|
||||
const TAB_ORDER = [
|
||||
'/dashboard', '/dashboard/apps', '/dashboard/marketplace', '/dashboard/cloud',
|
||||
'/dashboard/mesh', '/dashboard/server', '/dashboard/web5', '/dashboard/fleet',
|
||||
'/dashboard/chat', '/dashboard/settings'
|
||||
]
|
||||
```
|
||||
Map each path to its route component's registered `name` (check `router/index.ts` route defs) to produce `mainTabComponentNames` for Dashboard.vue's `<KeepAlive :include>`.
|
||||
|
||||
---
|
||||
|
||||
### Main-tab view conversions (Apps.vue, Mesh.vue, Server.vue, Web5.vue, marketplace/discover — D-02-gated)
|
||||
|
||||
**Analog:** `neode-ui/src/views/Cloud.vue` (already the most SWR-converted main-tab-adjacent view; 1029 lines, use Grep-then-targeted-Read for any further detail, not a full read)
|
||||
|
||||
**Imports pattern** (`Cloud.vue:405,410`):
|
||||
```typescript
|
||||
import { computed, ref, watch, onMounted } from 'vue'
|
||||
import { useCachedResource } from '../composables/useCachedResource'
|
||||
```
|
||||
|
||||
**Core SWR resource-definition pattern** (`Cloud.vue:510-524`):
|
||||
```typescript
|
||||
// Federation peers — cached so the Folders tab's peer cards paint instantly
|
||||
// on revisit while the list revalidates behind them.
|
||||
const peersResource = useCachedResource<PeerNode[]>({
|
||||
key: 'cloud.peer-nodes',
|
||||
fetcher: async (signal) => {
|
||||
const result = await rpcClient.federationListNodes()
|
||||
void signal
|
||||
return result?.nodes ?? []
|
||||
},
|
||||
ttlMs: 30_000,
|
||||
immediate: false, // kicked from onMounted (keeps the legacy load order)
|
||||
})
|
||||
const peerNodes = computed(() => peersResource.entry.data ?? [])
|
||||
const peersLoading = computed(() => peersResource.entry.loadState === 'loading')
|
||||
const peersRefreshing = computed(() => peersResource.entry.loadState === 'refreshing')
|
||||
```
|
||||
|
||||
**`onMounted` orchestration + error-keep-last-value pattern** (`Cloud.vue:949-968`, excerpted from grep hits at those lines):
|
||||
```typescript
|
||||
onMounted(async () => {
|
||||
// ... prior setup ...
|
||||
await peersResource.refresh()
|
||||
const e = peersResource.entry
|
||||
if (e.error) loadError.value = e.error // keep-last-known-value; surface error in a banner, not a toast
|
||||
})
|
||||
```
|
||||
This mirrors D-07 exactly: silent keep-last-value on background failure, explicit-refresh-only error surfacing.
|
||||
|
||||
**Per-view conversion checklist derived from RESEARCH.md's Concrete Findings table** (use during D-02 profiling, not blanket):
|
||||
- Mesh.vue: `onMounted` already does `await Promise.all([...6 calls...])` — NOT a waterfall; convert each of the 6 fetches into a `useCachedResource` key (nothing cached today) rather than touching the parallelization.
|
||||
- Server.vue (889 lines): 7 fire-and-forget calls in `onMounted` (line ~831) — already parallel; convert each to `useCachedResource` if profiling confirms uncached-refetch is the cause.
|
||||
- Apps.vue: WebSocket-pushed store data, no per-mount RPC — likely KeepAlive-only fix (remount storm), not a caching conversion.
|
||||
- Marketplace/Discover: not yet code-inspected — needs its own profiling pass before assigning a fix category.
|
||||
|
||||
---
|
||||
|
||||
### `neode-ui/src/views/ContainerAppDetails.vue` (secondary screen, serial-waterfall fix)
|
||||
|
||||
**Analog:** itself — the exact anti-pattern to fix in place (Pattern 3, RESEARCH.md)
|
||||
|
||||
**Current serial waterfall** (lines 169-173):
|
||||
```typescript
|
||||
onMounted(async () => {
|
||||
await loadContainer()
|
||||
await loadLogs()
|
||||
await loadHealthStatus()
|
||||
})
|
||||
```
|
||||
|
||||
**Independent load functions confirming no cross-dependency** (lines 175-202):
|
||||
```typescript
|
||||
async function loadContainer() {
|
||||
loading.value = true
|
||||
error.value = null
|
||||
try {
|
||||
const status = await store.getContainerStatus(appId.value)
|
||||
container.value = status
|
||||
} catch (e) {
|
||||
error.value = e instanceof Error ? e.message : t('common.error')
|
||||
} finally {
|
||||
loading.value = false
|
||||
}
|
||||
}
|
||||
|
||||
async function loadLogs() {
|
||||
logsLoading.value = true
|
||||
try {
|
||||
logs.value = await store.getContainerLogs(appId.value, 100)
|
||||
} catch (e) {
|
||||
if (import.meta.env.DEV) console.error('Failed to load logs:', e)
|
||||
} finally {
|
||||
logsLoading.value = false
|
||||
}
|
||||
}
|
||||
|
||||
async function loadHealthStatus() {
|
||||
await store.fetchHealthStatus()
|
||||
healthStatus.value = store.getHealthStatus(appId.value)
|
||||
}
|
||||
```
|
||||
Each sets its own `loading`/`logsLoading` ref independently and reads no shared intermediate result — safe to parallelize:
|
||||
```typescript
|
||||
onMounted(async () => {
|
||||
await Promise.allSettled([loadContainer(), loadLogs(), loadHealthStatus()])
|
||||
})
|
||||
```
|
||||
Note other call sites in the same file (lines ~205-240) also `await loadContainer(); await loadHealthStatus()` sequentially in refresh/action handlers — check each for the same independence property before parallelizing (don't blanket-apply beyond the `onMounted` case without verifying).
|
||||
|
||||
---
|
||||
|
||||
### Secondary screens converting to keyed `useCachedResource` (AppDetails.vue and similar, D-04)
|
||||
|
||||
**Analog:** `neode-ui/src/views/Cloud.vue`'s resource pattern above, keyed per item instead of globally.
|
||||
|
||||
**Key-naming convention to follow** (per CONTEXT.md D-04 and RESEARCH.md's Don't-Hand-Roll table):
|
||||
```typescript
|
||||
const detailsResource = useCachedResource<AppDetails>({
|
||||
key: `app-details:${appId.value}`,
|
||||
fetcher: (signal) => rpcClient.call({ method: 'apps.get-details', params: { appId: appId.value }, signal, dedup: true }),
|
||||
ttlMs: 30_000, // tune per D-06; shorter for fast-moving sub-resources
|
||||
})
|
||||
```
|
||||
No `<KeepAlive>` for these components (D-04) — component instance is NOT persisted, only the data cache is, so repeat opens still fully mount/unmount but paint instantly from `entry.data` before any refetch resolves.
|
||||
|
||||
---
|
||||
|
||||
### `neode-ui/src/views/Chat.vue` (AIUI iframe URL builder, D-14 UX defaults)
|
||||
|
||||
**Analog:** itself — extend the existing query-string builder pattern.
|
||||
|
||||
**Current URL-builder pattern** (lines 74-82):
|
||||
```typescript
|
||||
const aiuiUrl = computed(() => {
|
||||
// Demo: ?mockArchy makes AIUI use its built-in mock node data (apps, system,
|
||||
// network, wallet, bitcoin, files) and &seed pre-loads the example chats.
|
||||
const demo = IS_DEMO ? '&mockArchy=1&seed=1' : ''
|
||||
const envUrl = import.meta.env.VITE_AIUI_URL
|
||||
if (envUrl) return `${envUrl}?embedded=true&hideClose=true${demo}`
|
||||
if (import.meta.env.PROD || IS_DEMO) return `/aiui/?embedded=true&hideClose=true${demo}`
|
||||
return ''
|
||||
})
|
||||
```
|
||||
D-14's two defaults (chat starts expanded; mobile starts on chat view not context view) would append additional query params here (e.g. `&expanded=1`, `&mobileView=chat`) following the exact same string-concatenation convention — IF AIUI's own source (sibling repo, NOT in this checkout per RESEARCH.md's Open Question 1) already reads such params. **Blocking dependency**: confirm AIUI source location/support before scoping this as line-of-code work — this file's pattern is ready, but the receiving side is unverified.
|
||||
|
||||
**Origin-validated postMessage listener pattern** (lines 92-103, useful if D-14 needs a postMessage handshake instead of/in addition to query params):
|
||||
```typescript
|
||||
function onAiuiMessage(event: MessageEvent) {
|
||||
if (!aiuiUrl.value) return
|
||||
// Validate origin — only accept messages from AIUI
|
||||
try {
|
||||
const expected = new URL(aiuiUrl.value, window.location.origin).origin
|
||||
if (event.origin !== expected) return
|
||||
} catch { return }
|
||||
if (event.data?.type === 'ready') {
|
||||
aiuiConnected.value = true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shared Patterns
|
||||
|
||||
### Stale-while-revalidate data cache
|
||||
**Source:** `neode-ui/src/composables/useCachedResource.ts` (full file, 107 lines)
|
||||
**Apply to:** Every main-tab conversion (D-02) and every secondary-screen conversion (D-04)
|
||||
```typescript
|
||||
const resource = useCachedResource<T>({
|
||||
key: 'some.unique.key', // or `templated:${id}` for per-item secondary screens
|
||||
fetcher: (signal) => rpcClient.call({ method: '...', signal, dedup: true }),
|
||||
ttlMs: 30_000, // default; tune per D-06
|
||||
})
|
||||
```
|
||||
Do not hand-roll a second `ref` + manual `sessionStorage` cache per view — this is the exact duplication RESEARCH.md's canonical_refs warns against.
|
||||
|
||||
### Request dedup for parallelized fetch groups
|
||||
**Source:** `neode-ui/src/api/rpc-client.ts` (`dedup: true` option, already used in `Cloud.vue`/`Server.vue`)
|
||||
**Apply to:** Any newly-parallelized `Promise.all`/`Promise.allSettled` group (Pattern 3 fixes) so concurrent identical calls from multiple mounted consumers collapse into one request.
|
||||
```typescript
|
||||
const res = await rpcClient.call<{ interfaces: NetworkInterface[] }>({
|
||||
method: 'network.list-interfaces',
|
||||
signal,
|
||||
dedup: true,
|
||||
maxRetries: 1,
|
||||
})
|
||||
```
|
||||
|
||||
### Background-refresh error handling (silent keep-last-value, D-07)
|
||||
**Source:** `neode-ui/src/views/Cloud.vue:966-968`
|
||||
**Apply to:** All `useCachedResource` consumers — never toast on background refresh failure; only surface errors via an explicit-refresh path.
|
||||
```typescript
|
||||
const e = peersResource.entry
|
||||
if (e.error) loadError.value = e.error // banner, not a toast
|
||||
```
|
||||
|
||||
### KeepAlive reactivation revalidation (new shared extension)
|
||||
**Source:** `neode-ui/src/composables/useCachedResource.ts` (extend, see above)
|
||||
**Apply to:** All views, automatically, once the hook is extended — no per-view code changes needed to get D-01's "background refresh on revisit" behavior.
|
||||
|
||||
## No Analog Found
|
||||
|
||||
| File | Role | Data Flow | Reason |
|
||||
|------|------|-----------|--------|
|
||||
| `.planning/phases/02-ui-performance/<findings-doc>.md` (D-10 deliverable) | doc/config | batch | Documentation deliverable, not code — no code analog applicable; format is Claude's discretion per RESEARCH.md Open Question 2 (narrative + DevTools/performance.mark numbers recommended) |
|
||||
| KeepAlive template wiring in `Dashboard.vue` | route/container | request-response | No existing `<KeepAlive>` usage anywhere in the codebase (`grep -r "KeepAlive" neode-ui/src` = 0 hits) — pattern comes from Vue Router 4 official docs, not an in-repo analog |
|
||||
| AIUI-side D-14 param handling | external app | event-driven | AIUI source not present in this checkout (sibling repo, unconfirmed location) — cannot pattern-map code that isn't accessible; planner must add a precondition/checkpoint task per RESEARCH.md Open Question 1 |
|
||||
|
||||
## Metadata
|
||||
|
||||
**Analog search scope:** `neode-ui/src/{views,composables,stores,api,views/dashboard}`
|
||||
**Files scanned:** Dashboard.vue, useCachedResource.ts, useRouteTransitions.ts, rpc-client.ts, resources.ts, Cloud.vue, ContainerAppDetails.vue, Chat.vue, App.vue (partial), plus grep sweeps across `views/*.vue` for `onMounted`/`useCachedResource`/`KeepAlive` usage (per RESEARCH.md's own prior codebase pass, cross-checked)
|
||||
**Pattern extraction date:** 2026-07-30
|
||||
Reference in New Issue
Block a user