# Contributing

Thanks for helping improve Iron. The project is still early, so the most useful
contributions are focused changes with tests and clear documentation updates.

## Development Setup

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

Run the API locally:

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

Open `http://127.0.0.1:8000/app`.

## Test Before Submitting

Run the full suite:

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

For UI changes, also run:

```bash
npm run build
.venv/bin/python scripts/ui_playwright_smoke.py
```

Review screenshots in `output/playwright/` before considering UI work complete.

## Pull Request Checklist

- The change is focused and described clearly.
- Tests were added or updated for behavior changes.
- UI changes were validated with Playwright when applicable.
- Documentation was updated if setup, behavior, or architecture changed.
- Generated/runtime files are not included.

## Code Style

- Backend code lives in `app/` and uses async FastAPI + SQLAlchemy patterns.
- Frontend code lives in `frontend/` and uses React, React Router, and
  TanStack Query.
- Keep browser file preview/download flows authenticated through the API client.
- Prefer clear names and small modules over clever abstractions.

## Project Status

Iron is a Product MVP Candidate. See:

- [docs/product.md](docs/product.md)
- [docs/architecture.md](docs/architecture.md)
- [docs/development.md](docs/development.md)