# Iron Web UI Technical Design Last updated: 2026-04-15 ## 1. Goal This document defines the first real Web UI implementation for Iron as a product, not as a backend demo shell. The design target is: - a browser-based personal cloud drive that feels familiar to users of mainstream drive products - a file-first experience, with storage and operational controls available when needed - a frontend architecture that can grow without forcing a backend rewrite ## 2. Product Direction Iron should feel like: - a calm personal drive for everyday browsing, upload, preview, and organization - a storage-aware control surface when the user wants to inspect health, jobs, or replica state Iron should not feel like: - a generic admin dashboard - a developer-only operations console - a backend demo that exposes storage complexity too early The default user mental model should be: - there is one drive - files live in one namespace - storage placement is handled by the system - operational details are inspectable but not required for normal use ## 3. UX Principles - file browsing is the center of the product - preview before download whenever possible - complex storage details stay secondary - important system state stays visible but low-noise - common actions should be reachable in one or two clicks - the desktop layout should resemble familiar drive products, while mobile should collapse into simple list-detail flows ## 4. Primary Information Architecture Recommended primary navigation: 1. Files 2. Uploads 3. Recycle Bin 4. Storage 5. Jobs Secondary entry points: - search - account/session menu - future settings/policies entry ## 5. Layout Model The app should use a three-zone desktop layout: - left sidebar: primary navigation and directory shortcuts - main workspace: listing, toolbar, breadcrumbs, upload flows - right detail panel: preview, metadata, storage status, contextual actions Mobile and narrow tablet should collapse to: - top bar - main content - bottom sheet or dedicated route for file detail ## 6. Visual Direction Reference class: - mainstream Web drive layout - product-first, not enterprise-heavy - spacious, legible, and calm Current visual language: - ownCloud-inspired file-product structure, without copying exact visual assets - desktop-first left navigation, central file workspace, and right contextual panels - compact first-screen layouts with pagination for long lists instead of page-length scrolling - restrained neutral surfaces, blue primary actions, high-contrast text, and light borders - UI changes must be reviewed from real Playwright screenshots before being considered complete ## 7. Frontend Technical Stack Recommended stack: - `Vite` - `React` - `TypeScript` - `React Router` - `TanStack Query` - `Radix UI` primitives only when needed later State strategy: - server state: `TanStack Query` - local UI state: React state and context - persistent auth/session state: small local storage wrapper Rationale: - Iron is a long-lived SPA-style product - the backend already owns API and routing responsibility - Vite keeps build and iteration simple - React Router and TanStack Query are enough for current complexity ## 8. App Structure Recommended source layout: ```text frontend/ src/ app/ App.tsx router.tsx providers.tsx components/ layout/ feedback/ files/ storage/ features/ auth/ files/ uploads/ recycle-bin/ storage/ jobs/ lib/ api/ auth/ format/ utils/ routes/ styles/ ``` Guidance: - keep route-level pages under `routes/` - keep API wrappers under `lib/api/` - keep reusable visual building blocks under `components/` - keep feature-specific hooks and rendering helpers in each feature folder ## 9. Route Plan Initial route map: - `/app/login` - `/app/files` - `/app/files/:directoryId` - `/app/uploads` - `/app/recycle-bin` - `/app/storage` - `/app/jobs` Behavior: - `/app` should redirect authenticated users to `/app/files` - unauthenticated users should be sent to `/app/login` ## 10. Data and API Integration The first Web UI should reuse the current backend API surface. Auth: - `POST /api/auth/login` - `GET /api/auth/me` - `POST /api/auth/logout` Files and directories: - `GET /api/directories/{directory_id}/children` - `GET /api/files/{file_id}` - `GET /api/files/{file_id}/download` - `GET /api/files/{file_id}/preview` - `GET /api/files/{file_id}/stream` - `POST /api/files/{file_id}/rename` - `POST /api/files/{file_id}/move` - `DELETE /api/files/{file_id}` - `POST /api/files/{file_id}/restore` - `GET /api/files/recycle-bin` - `POST /api/directories` - `POST /api/directories/{directory_id}/rename` - `POST /api/directories/{directory_id}/move` Uploads: - `POST /files` - `HEAD /files/{upload_id}` - `PATCH /files/{upload_id}` - `POST /api/uploads/{upload_id}/finalize` Operations: - `GET /api/backends` - `POST /api/backends/{backend_id}/check` - `POST /api/backends/{backend_id}/disable` - `GET /api/jobs` - `GET /api/jobs/{job_id}` - `POST /api/jobs/{job_id}/retry` - `POST /api/jobs/run-pending` - `POST /api/jobs/enqueue-health-checks` - `POST /api/jobs/enqueue-full-reconcile` Browser content access: - JSON APIs use bearer-token `Authorization` headers through the shared API client - file download, preview, and stream actions must not use naked `/api/files/...` URLs in media tags or `window.open` - browser preview/download should fetch the file with authorization, create an object URL, and revoke it after use - Playwright E2E must cover authenticated file access whenever these flows change ## 11. MVP Page Scope ### 11.1 Files Must include: - breadcrumb navigation - file/folder listing - list and grid view toggle - select item - right-side detail panel - preview for image, PDF, and video-capable files - rename, move, delete, download actions - create folder action ### 11.2 Uploads Must include: - file picker - drag and drop - upload queue - progress display - finalize into current directory ### 11.3 Recycle Bin Must include: - deleted file list - restore action - metadata visibility ### 11.4 Storage Must include: - backend cards/list - health state - last checked time - disable action - trigger check action ### 11.5 Jobs Must include: - recent jobs list - status emphasis - retry for retryable/failed jobs - trigger run pending - enqueue health checks - enqueue full reconcile ## 12. Interaction Model Toolbar behavior in Files: - primary action: upload - secondary actions: new folder, refresh, view toggle - selection actions move into detail panel and contextual menus Detail panel behavior: - opens on item selection - shows metadata immediately - shows preview when supported - keeps actions grouped by safety Feedback behavior: - use inline toasts or banners for successful mutations - keep destructive confirmations explicit - show loading skeletons instead of blank content ## 13. Accessibility and Responsiveness The first Web UI should include: - keyboard reachable navigation - visible focus states - semantic buttons, forms, lists, and headings - color contrast suitable for long sessions - responsive behavior for widths down to mobile phone layouts ## 14. Delivery Sequence Recommended implementation order: 1. frontend scaffold and shared layout 2. auth flow and route guards 3. files page and detail panel 4. uploads page and upload client 5. recycle bin 6. storage and jobs pages 7. polish, responsiveness, and interaction refinement ## 15. Non-Goals For This Slice Do not block the first Web UI on: - advanced settings UI - full-text search - share links - policy editor UX - multi-window drag/drop complexity - perfect media derivative support The first goal is a strong file-first personal drive UI built on the current backend. ## 16. Current Implementation Snapshot Implemented as of 2026-04-15: - login and authenticated route guard - files workspace with local folder navigation, breadcrumbs, search, sort, list/grid toggle, pagination, contextual row actions, dialogs, and inspector - authenticated browser download and inline image preview via blob-backed object URLs - uploads page with drag/drop, file picker, queue, target folder tree, and pagination - recycle bin, storage, and jobs pages with compact desktop workspaces - Python Playwright smoke/E2E flow with screenshots under `output/playwright/` - pytest E2E entry at `tests/e2e/test_web_ui_playwright.py`