iron/docs/development.md

Development

This document captures the development workflow, test expectations, and UI quality rules for Iron.

Setup

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

Run Locally

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

Open:

http://127.0.0.1:8000/app

Default development credentials:

username: admin
password: changeme-iron

Tests

Full suite:

.venv/bin/python -m pytest

Current expected result:

66 passed

Browser E2E:

.venv/bin/python scripts/ui_playwright_smoke.py

Pytest E2E entry:

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

UI Change Standard

Any meaningful Web UI change must be validated against a real running service.

Required workflow:

1. build frontend assets with npm run build
2. run ./.venv/bin/python scripts/ui_playwright_smoke.py
3. review screenshots in output/playwright/
4. fix layout, spacing, overflow, or interaction issues
5. rerun the Playwright flow

The E2E flow currently covers:

• login
• files page render
• create folder
• upload text file
• authenticated file download
• upload image file
• authenticated inline image preview
• search
• uploads, recycle bin, storage, and jobs page render
• browser /api 4xx/5xx failures during the flow

Runtime Artifacts

Do not commit:

• .venv/
• .uv-cache/
• node_modules/
• output/
• .iron-storage/
• .iron-temp/
• local databases
• Python caches

Documentation Rules

• Keep README.md concise and user-facing.
• Keep contributor instructions in CONTRIBUTING.md.
• Keep coding-agent instructions in AGENTS.md.
• Keep deeper project docs in docs/.
• Use relative links in Markdown.
• Update docs when changing setup, commands, architecture, or user-visible behavior.