# Iron

Personal cloud drive gateway and Web app.

## Current Status

- product requirements drafted in `docs/`
- technical architecture drafted in `docs/`
- Python backend foundation implemented
- product Web UI implemented with `Vite + React + TypeScript`
- local auth, upload, local persistence, S3 reconciliation, policy-driven replica placement, declarative background jobs, full-system reconcile, preview artifact generation, metadata export/validate/integrity/import, and a product-oriented browser app are available
- the current Web app includes files, uploads, recycle bin, storage, and jobs pages with a desktop-first drive layout
- authenticated download and inline preview flows are covered by Python Playwright E2E tests
- current automated baseline: `66` passing tests
- next primary implementation focus should be hardening the product experience through real-browser regression, not broad backend expansion

## Backend

Create the local environment with `uv`:

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

Run the API locally:

```bash
.venv/bin/python -m uvicorn app.main:app --reload
```

Open the current browser app at:

- [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app)

Default local bootstrap credentials:

- username: `admin`
- password: `changeme-iron`

Environment overrides:

- `IRON_DATABASE_URL`
- `IRON_BOOTSTRAP_USERNAME`
- `IRON_BOOTSTRAP_PASSWORD`
- `IRON_AUTH_SESSION_TTL_HOURS`
- `IRON_UPLOAD_TEMP_DIR`
- `IRON_LOCAL_STORAGE_DIR`
- `IRON_CACHE_DIR`
- `IRON_JOB_POLL_INTERVAL_SECONDS`
- `IRON_JOB_BATCH_SIZE`

Restore safety:

- metadata import requires `confirm_replace=true`
- metadata import also requires a fresh validation token from `POST /api/exports/metadata/restore-plan`

## Tests

```bash
.venv/bin/python -m pytest
```

Current expected result:

- `66 passed`

Run the browser E2E flow directly with:

```bash
.venv/bin/python scripts/ui_playwright_smoke.py
```

Or through pytest:

```bash
.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py
```

## Implemented Foundations

- FastAPI application bootstrap
- async SQLAlchemy engine setup
- initial ORM entity definitions
- Alembic migrations
- local auth bootstrap and bearer-token sessions
- React Web app at `/app`
- authenticated browser download and preview using bearer-token-backed blob fetches
- local + S3 runtime storage foundation
- persisted placement policy controls and placement preview API
- SQLite-backed job records, declarative reconcile flows, and metadata export/validate/integrity/import APIs
- health and readiness endpoints
- baseline automated tests

## Handoff

For the most useful handoff view before continuing development, start here:

- [docs/handoff.md](/Users/bytedance/iron/docs/handoff.md:1)