iron/docs/handoff.md

Iron Engineering Handoff

Last updated: 2026-04-15

1. What This Document Is For

This is the fastest way for another AI or engineer to continue work on Iron without re-reading the full project history.

Read this first, then use the other docs as references:

• product scope: requirements.md
• gap analysis: mvp-status.md
• implementation architecture: technical-architecture-draft.md
• API details: api-design.md
• schema details: database-schema.md

2. Current Truth

The project is no longer architecture-only.

It already has:

• async FastAPI backend
• SQLite + SQLAlchemy ORM
• Alembic migrations
• local auth with persisted bearer-token sessions
• directories, files, recycle bin, rename, move
• tus uploads
• local backend persistence
• S3 runtime replication and remote fallback reads
• declarative reconcile jobs
• metadata export, validate, integrity, restore-plan, and guarded import
• placement policy persistence and placement preview API
• a frontend app scaffold at /app built with Vite + React + TypeScript
• product routes for files, uploads, recycle bin, storage, and jobs
• a desktop-first Web UI with file list, contextual inspector, upload queue, recycle bin, storage, and jobs surfaces
• Python Playwright E2E coverage for login, create folder, upload, authenticated download, authenticated image preview, search, and page rendering

It now has a product-usable Web frontend foundation, but it still needs user-facing hardening before calling it a polished release.

The most honest stage label is still:

• Product MVP Candidate

3. Current Verified Baseline

Use uv and the local virtualenv:

UV_CACHE_DIR=.uv-cache uv venv .venv
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python -e '.[dev]'

Run tests with:

export UV_CACHE_DIR=.uv-cache && .venv/bin/python -m pytest

Current expected result:

• 66 passed

If new work changes behavior, update this number in:

• README.md
• mvp-status.md
• this file

4. What Is Implemented

4.1 Backend Capabilities

• auth:
  • bootstrap admin user
  • login
  • logout
  • current user
• namespace:
  • create/list directories
  • mixed children listing
  • file detail
  • file and directory rename/move
  • recycle-bin delete/restore for files
• upload:
  • tus create/head/patch
  • finalize to file metadata
• storage:
  • local backend object persistence
  • S3 adapter runtime path
  • remote fallback read into local cache
• preview:
  • image/PDF inline preview
  • generic video stream through HTTP Range
  • preview artifact rows and generation jobs
• ops:
  • backend list/create/check/disable
  • jobs list/detail/retry/run
  • enqueue full reconcile
  • enqueue backend health checks
  • file reconcile
• recovery:
  • metadata export
  • metadata validate
  • metadata integrity
  • restore plan with validation token
  • guarded metadata import

4.2 Placement Controls

This area is complete enough for backend MVP work.

Current placement behavior supports:

• policies by file class
• local requirement flag
• stable and opportunistic replica counts
• ordered preferred backend ids
• excluded backend ids
• optional max_non_local_size_bytes
• placement preview API
• reconcile jobs converging toward policy-selected targets

Main files:

• app/services/policy_service.py
• app/api/routes/policies.py
• tests/test_policy_routes.py
• tests/test_placement_jobs.py

5. Main Remaining Work

5.1 P0: Product Frontend

This is the main next focus.

Needed next:

• deepen the new frontend foundation into a more polished daily-usable product
• improve directory navigation and breadcrumbs
• harden upload progress UX and directory targeting
• improve preview and detail-panel behavior
• refine mobile behavior and browser session handling
• extend Playwright E2E coverage as each product flow becomes real

5.2 P1: Backend Hardening

These are still useful, but they are no longer the main gating path:

• stronger preview derivative generation
• post-restore operational tooling
• richer replica verification and repair visibility
• more sophisticated cache observability and eviction

5.3 Post-MVP / Roadmap

• Aliyun adapter
• Baidu adapter
• desktop client
• mobile client
• share links
• search

6. Recommended Next Sequence

If another AI continues from here, the recommended order is:

1. preserve the current desktop-first drive UX and avoid reverting to dashboard-style empty panels
2. keep browser file access going through authenticated blob fetches, not naked /api/files/... media URLs
3. extend Playwright E2E coverage when adding preview, download, upload, or mutation flows
4. only after product hardening, return to backend polish such as richer preview derivatives

7. Important Repo Realities

These details are easy to get wrong if someone only reads the older architecture docs:

• config is currently a lightweight cached dataclass module, not pydantic-settings
• the frontend source now lives in frontend/ and builds into app/web/dist
• tus endpoints live under /files, outside the normal /api JSON namespace
• the backend uses persisted bearer tokens today
• metadata import is intentionally guarded by:
  • confirm_replace=true
  • validation_token from restore-plan

8. Where To Look In Code

High-signal entry points:

• app bootstrap: app/main.py
• API composition: app/api/router.py
• auth: app/services/auth_service.py
• files: app/services/file_service.py
• uploads: app/services/upload_service.py
• jobs: app/services/job_service.py
• storage: app/services/storage_service.py
• placement: app/services/policy_service.py
• frontend entry: frontend/src/app/App.tsx
• frontend routes: frontend/src/app/router.tsx
• frontend API client: frontend/src/lib/api.ts
• frontend styles: frontend/src/styles/app.css
• Playwright E2E: scripts/ui_playwright_smoke.py
• pytest E2E entry: tests/e2e/test_web_ui_playwright.py
• built app entry: app/web/dist/index.html

9. Testing Guidance

When continuing development:

• keep using uv + .venv
• prefer adding tests in the same slice as each feature
• run Python Playwright for UI-affecting work
• update docs after meaningful milestone changes
• do not let README, MVP status, and actual test count drift apart

Current test files:

• tests/test_auth_routes.py
• tests/test_backend_routes.py
• tests/test_directory_routes.py
• tests/test_export_routes.py
• tests/test_file_routes.py
• tests/test_job_routes.py
• tests/test_placement_jobs.py
• tests/test_policy_routes.py
• tests/test_system_routes.py
• tests/test_upload_routes.py
• tests/test_web_routes.py

10. Suggested Handoff Prompt

If another AI is about to continue, a good short prompt is:

Read /Users/bytedance/iron/docs/handoff.md first, treat it as the current source of truth, then continue from the frontend-first sequence unless new user instructions override it.