iron/docs/web-ui-technical-design.md

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:

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