iron/README.md

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:

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:

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

Open the current browser app at:

• 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

.venv/bin/python -m pytest

Current expected result:

• 66 passed

Run the browser E2E flow directly with:

.venv/bin/python scripts/ui_playwright_smoke.py

Or through pytest:

.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