tutur3u/platform/tuturuuu-satellite-app-ux

Tuturuuu Satellite App UX

Core Workflow

Use this skill for standalone app surfaces under apps/* that behave like satellite apps rather than sections inside apps/web.

For shell or auth changes, trace the target app's relevant proxy.ts, providers, workspace layout, navigation, or app-session routes. A local UI change does not require a full shell audit.

App Shell Checklist

• Use @tuturuuu/satellite providers, i18n helpers, constants, and app-session

helpers where the app already follows that pattern.

• Keep auth target names consistent across proxy, verify-token, refresh, logout,

and server session reads.

• Preserve workspace route shapes and locale handling. New dashboard routes need

navigation aliases, icons, permissions or access gates, and empty states.

• Build the actual app workspace as the first screen. Avoid marketing-style

landing pages for operational apps.

• Prefer a focused app shell with clear primary navigation, search/filter tools,

and compact repeated actions over a generic dashboard card wall.

• Add strings to the owning app's English and Vietnamese bundles. If shared UI

strings are added, update every app bundle that ships that shared surface.

Data And Mutation Rules

• Use TanStack Query for client fetching/mutation.
• Put shared app API clients behind packages/internal-api/src/* when code is

reused outside one route.

• Do not add raw client-side app API fetches.
• Check shared clients' actual paths when configuring API fallbacks. Mind's

workspace selector uses Web-owned /api/workspaces/* as well as /api/v1/*; its /api/* fallback preserves local product and auth handlers. Regression: apps/mind/src/next-config.test.ts exercises Next's rewrite matcher.

• Keep protected data reads and writes behind server-owned APIs. Do not expose

privileged Supabase access to satellite clients.

Cross-App Parity

For Calendar or Finance, assume the standalone app and the apps/web counterpart move together unless the user explicitly scopes an exception.

For other satellite apps, inspect whether a shared package or apps/web counterpart already owns the behavior before duplicating logic in the app.

Verification

Run focused tests for the target app first, then required repo checks:

bun i18n:add --app chat --key common.save --value en="Save" --value vi="Lưu"
bun type-check:chat
bun i18n:sort
bun i18n:check

Use bun i18n:add for satellite translation key add/remove/replace work when possible; use --entries or --entries-file for bulk updates so every detected locale file is updated and sorted together. Reserve manual message JSON edits for broad prose rewrites or value-only updates. Finish with bun validate for TypeScript, JavaScript, messages, or repo config changes unless an unrelated pre-existing blocker prevents it. Finite builds needed to validate the authorized change may run. Start long-lived servers only when requested or needed for explicitly requested runtime verification.

Public documents

For explicitly public surfaces, use @tuturuuu/satellite/public, its theme-only provider and injected Link/Image adapters. Avoid the authenticated default barrel, providers and account controls in the public document graph. Public labels come from explicit app translations; sign-in is a link, never a session lookup. See packages/satellite/README.md and the public-document decision in apps/docs/platform/architecture/satellite-apps.mdx. The owning app supplies its existing UI CSS processor; dependency and lockfile changes require normal custody. Source graph/SSR tests do not replace emitted bundle inspection or hosted cache-hit acceptance. Header-only policy must retain unsafe headers and preserve MIME, streaming/status and native asset ownership.