# 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](/Users/bytedance/iron/docs/requirements.md:1)
- gap analysis: [mvp-status.md](/Users/bytedance/iron/docs/mvp-status.md:1)
- implementation architecture: [technical-architecture-draft.md](/Users/bytedance/iron/docs/technical-architecture-draft.md:1)
- API details: [api-design.md](/Users/bytedance/iron/docs/api-design.md:1)
- schema details: [database-schema.md](/Users/bytedance/iron/docs/database-schema.md:1)

## 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:

```bash
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:

```bash
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](/Users/bytedance/iron/README.md:1)
- [mvp-status.md](/Users/bytedance/iron/docs/mvp-status.md:1)
- 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](/Users/bytedance/iron/app/services/policy_service.py:1)
- [app/api/routes/policies.py](/Users/bytedance/iron/app/api/routes/policies.py:1)
- [tests/test_policy_routes.py](/Users/bytedance/iron/tests/test_policy_routes.py:1)
- [tests/test_placement_jobs.py](/Users/bytedance/iron/tests/test_placement_jobs.py:1)

## 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](/Users/bytedance/iron/app/main.py:1)
- API composition: [app/api/router.py](/Users/bytedance/iron/app/api/router.py:1)
- auth: [app/services/auth_service.py](/Users/bytedance/iron/app/services/auth_service.py:1)
- files: [app/services/file_service.py](/Users/bytedance/iron/app/services/file_service.py:1)
- uploads: [app/services/upload_service.py](/Users/bytedance/iron/app/services/upload_service.py:1)
- jobs: [app/services/job_service.py](/Users/bytedance/iron/app/services/job_service.py:1)
- storage: [app/services/storage_service.py](/Users/bytedance/iron/app/services/storage_service.py:1)
- placement: [app/services/policy_service.py](/Users/bytedance/iron/app/services/policy_service.py:1)
- frontend entry: [frontend/src/app/App.tsx](/Users/bytedance/iron/frontend/src/app/App.tsx:1)
- frontend routes: [frontend/src/app/router.tsx](/Users/bytedance/iron/frontend/src/app/router.tsx:1)
- frontend API client: [frontend/src/lib/api.ts](/Users/bytedance/iron/frontend/src/lib/api.ts:1)
- frontend styles: [frontend/src/styles/app.css](/Users/bytedance/iron/frontend/src/styles/app.css:1)
- Playwright E2E: [scripts/ui_playwright_smoke.py](/Users/bytedance/iron/scripts/ui_playwright_smoke.py:1)
- pytest E2E entry: [tests/e2e/test_web_ui_playwright.py](/Users/bytedance/iron/tests/e2e/test_web_ui_playwright.py:1)
- built app entry: [app/web/dist/index.html](/Users/bytedance/iron/app/web/dist/index.html:1)

## 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](/Users/bytedance/iron/tests/test_auth_routes.py:1)
- [tests/test_backend_routes.py](/Users/bytedance/iron/tests/test_backend_routes.py:1)
- [tests/test_directory_routes.py](/Users/bytedance/iron/tests/test_directory_routes.py:1)
- [tests/test_export_routes.py](/Users/bytedance/iron/tests/test_export_routes.py:1)
- [tests/test_file_routes.py](/Users/bytedance/iron/tests/test_file_routes.py:1)
- [tests/test_job_routes.py](/Users/bytedance/iron/tests/test_job_routes.py:1)
- [tests/test_placement_jobs.py](/Users/bytedance/iron/tests/test_placement_jobs.py:1)
- [tests/test_policy_routes.py](/Users/bytedance/iron/tests/test_policy_routes.py:1)
- [tests/test_system_routes.py](/Users/bytedance/iron/tests/test_system_routes.py:1)
- [tests/test_upload_routes.py](/Users/bytedance/iron/tests/test_upload_routes.py:1)
- [tests/test_web_routes.py](/Users/bytedance/iron/tests/test_web_routes.py:1)

## 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.