docs/frontend-home-projects.md

MediaRouter Frontend Phase 2: Home and Projects

Scope

Phase 2 replaces the operation-oriented content of the existing /dashboard route with a project-oriented Home experience and introduces the frontend project domain. It does not change the Workspace Shell, backend contracts, social behavior, or unfinished product areas.

The existing authenticated shell continues to wrap Home, Assets, and the new project route structure:

Workspace Shell
├── /dashboard              HomeWorkspace
├── /assets                 MediaAssetsBrowser
├── /projects               ProjectsPage
└── /projects/[projectId]   ProjectProvider + ProjectDetail

/projects and /projects/[projectId] are safe, capability-gated route foundations. The sidebar and command palette do not advertise them until the backend provides an authoritative projects API and the signed-in user has projects:read.

Backend capability audit

Available now

• Server-side authoritative workspaces, users, and memberships exist in the tenancy database and are enforced through RLS.
• Canonical media assets are workspace-owned server records.
• GET /v1/social/assets exposes the workspace-owned media assets registered for publishing, including filename, MIME type, size, metadata, and creation time.
• GET /v1/social/jobs exposes workspace-scoped publishing jobs.
• Generation requests/jobs exist under /v1/generation/*.
• Template discovery is available through /v1/templates.
• Operations are discoverable through OpenAPI.

Missing now

There is no backend projects resource: no projects table/model, no project ownership relation, no project metadata, no project-to-asset/job/template relation, and no project API path in OpenAPI. Workspace membership data is server-side only; there is no browser-facing workspace membership/switching contract.

For this reason, the frontend never invents a project, writes browser-local persistence, shows a Create Project action, or emits a project mutation. ProjectApiUnavailableError is the explicit façade behavior when no canonical endpoint exists.

Home architecture

features/home/home-workspace.tsx composes the existing design-system and workspace primitives into:

• greeting based on authenticated user context;
• Continue Working, prioritizing a real active job and then the latest registered asset;
• Recent Projects, which is an explicit unavailable state until a project API exists;
• Active Work from useLiveJobs() and the existing social-jobs query only;
• Recent Assets from useSocialMediaAssets();
• Suggested Actions generated only from resolved navigation/capabilities; and
• concise Activity from the same real job records.

Home contains no hard-coded counters, progress values, projects, workspace names, or action placeholders. Upload, project creation, import, AI, and similar actions are intentionally absent until their authoritative APIs and UI flows exist.

Project architecture

The project feature is isolated under frontend/features/projects/:

• types.ts defines the typed frontend project domain and maps only explicit backend fields.
• lib/api/projects.ts discovers a /vN/projects collection and /vN/projects/{id} detail API from OpenAPI. It fails closed otherwise.
• api/queries.ts owns project query keys, collection/detail queries, and a shared invalidation boundary for future audited mutations.
• context/project-provider.tsx supplies route-derived projectId, project data, loading/error state, project availability, and read/write permission state. It uses TanStack Query rather than a project Zustand store.
• components/ contains ProjectCard, ProjectGrid, ProjectList, ProjectHeader, ProjectActions, page, and detail adapters.

Project cards can represent thumbnail, title, description, timestamps, status, owner, asset count, job status, and selection using real response fields. Only Open project is implemented in the action menu because no backend operation supports rename, duplicate, archive, delete, favorite, or share.

Data fetching and mutations

All network access continues through lib/api/* and TanStack Query. Components do not use fetch().

Domain	Query source	Current behavior
Projects	OpenAPI-discovered project facade	Disabled/unavailable until both collection and detail reads exist
Assets	Existing useSocialMediaAssets()	Real workspace-scoped publishable media assets
Active work	Existing useLiveJobs() and social jobs query	Real records only; no parallel custom polling
Templates	Existing useTemplates()	Backend registry
Operations	Existing backend discovery	OpenAPI metadata

No project mutation is exposed today because the backend lacks a schema to validate or authorize one. The feature already has projectKeys and useProjectInvalidation() so a future audited mutation can invalidate correctly without changing page components.

Assets and search

The existing /assets route now renders the real publishing-asset collection via reusable AssetCard, AssetGrid, and AssetList components. It does not claim to be a complete canonical asset repository; it only displays the assets the current backend actually exposes.

Global Search retains its shared command/search infrastructure and now maps real project records (when available), social media assets, and publishing jobs. Asset results use /assets?asset=<id> to select the loaded authoritative asset. Project results use /projects/<id>. Routes are still filtered by resolved navigation, capability, permission, and feature-flag context.

Commands and permissions

registerProjectCommands() registers Open Projects only when the projects API is discovered. It does not register create, delete, share, or recent-project commands without authoritative support.

Project navigation requires both projects capability metadata and projects:read. The frontend permission vocabulary has reserved projects:read and projects:write for the future backend contract; neither grants access by itself while the capability is absent.

Responsive and accessibility behavior

• Project and asset grids use one column on narrow screens, two at small/tablet widths, three at large desktop widths, and four on very wide displays.
• Project lists use the reusable keyboard-accessible table system with client-side search, sorting, and selection over already loaded records only.
• Cards expose descriptive links, selection controls have labels, action menus use Radix focus management, and all interactive controls use design-system focus styles and touch-friendly sizing.
• Home does not load editor, timeline, AI Studio, or analytics modules.

Backend requirements for the next phase

To activate actual project persistence, the backend needs at minimum:

1. GET /v1/projects — workspace-authorized, paginated project records with stable IDs and projects:read authorization.
2. GET /v1/projects/{project_id} — workspace-authorized detail lookup returning 404 for missing/non-owned records.
3. POST /v1/projects — a strict, documented creation schema and projects:write authorization.
4. A persisted project ownership model linked to the authoritative workspace/user membership boundary.
5. Explicit project metadata/capability fields, rather than browser assumptions, for permitted actions.
6. Workspace-authorized relations or summary fields for project assets, jobs, templates/recipes, and future publishing/automation resources.
7. Optional audited PATCH/archive/delete/duplicate/share endpoints only when their behavior, authorization, and idempotency contracts are ready.

Once these endpoints are available, the project facade will discover the routes from OpenAPI, the sidebar/command entry will resolve, queries will activate, and a schema-driven creation flow can be implemented without an architecture rewrite.