rules.md

# Rules

Contract for every contributor — human or AI — working in this repo.

## Project Overview

`automAIta` is a deployment-ready boilerplate for HuggingFace Spaces.

- **Backend:** FastAPI (MVC) managed by `uv`, defined in `backend/pyproject.toml`.
- **Frontend:** Vite + React + TypeScript + Tailwind + PWA. No app frameworks.
- **Container:** one Docker image, single port `7860`. FastAPI serves the built React bundle as static files at `/` and the API under `/api/*`.
- **Deploy:** GitHub `main` → `.github/workflows/sync-to-hf.yml` mirrors the repo to a HuggingFace Space, which rebuilds automatically.

## Scope & Goals

- Stay a **boilerplate**. The only "feature" is `App.tsx` proving the `/api/status` round-trip works.
- New projects fork this repo and fill it in — they should not have to rewire Docker, ports, the workflow, or the layout.

## Coding Rules

- **No hardcoded values.** Backend goes through `app/core/config.py` (env prefix `AUTOMAITA_`). Frontend uses Vite env vars (`import.meta.env.VITE_*`) when needed.
- **Backend MVC layering:**
  - `controllers/` — `APIRouter`s only. Thin: parse, call a service, return.
  - `services/` — business logic. No FastAPI imports.
  - `schemas/` — pydantic request/response DTOs.
  - `models/` — pydantic domain models.
  - `core/` — config, lifespan, anything cross-cutting.
- **Frontend:**
  - TypeScript `strict` is on. Don't downgrade it.
  - Tailwind is the only styling system. **No** Material UI, Chakra, Mantine, shadcn, etc., without explicit approval.
  - **No** state libraries (Redux/Zustand/Jotai) or routers (React Router/TanStack Router) until the project actually needs one.
  - All API calls go through `src/api/client.ts`.
- **Single-port contract.** The container exposes only `7860`. Don't introduce nginx, supervisord, or a second process. FastAPI mounts the static SPA itself.
- **Same-origin in prod.** API client uses relative URLs (`/api/...`). Don't hardcode `http://localhost:8000` or any HF URL.

## Agent Behavior Rules

- Never bypass the `frontend/` ↔ `backend/` boundary — they communicate over HTTP, not shared imports.
- Never break the **single-port** contract or the **non-root UID 1000** Dockerfile.
- Never edit `.github/workflows/sync-to-hf.yml` to add deploy logic that belongs inside the container — the workflow's job is mirroring, nothing else.
- Preserve the Dockerfile's two-stage shape (`frontend-build` → `runtime`). New build steps go inside an existing stage; don't add stages without need.
- When adding a backend route, create a controller in `app/controllers/`, register it in `app/main.py`, and put the logic in `app/services/`.

## Workflow Rules

- **Local dev (split):**
  - Backend: `cd backend && uv sync && uv run uvicorn app.main:app --reload --port 8000`
  - Frontend: `cd frontend && npm install && npm run dev` (proxy handles `/api`).
- **Container parity (run what HF runs):** `docker build -t automaita . && docker run --rm -p 7860:7860 automaita` → http://localhost:7860.
- **Deploy:** push to GitHub `main`. Required repo secrets: `HF_TOKEN`, `HF_USER`, `HF_SPACE_NAME`.
- Don't push directly to the HF Space repo — let the action do it, otherwise you fork history.

## Conventions

- **Env var prefix:** `AUTOMAITA_` (backend), `VITE_` (frontend).
- **API prefix:** all backend routes live under `/api/*`. The PWA service worker explicitly excludes `/api/*` from navigation fallback.
- **Filenames:**
  - Backend: snake_case modules, controllers suffixed `_controller.py`, services suffixed `_service.py`.
  - Frontend: PascalCase for components (`App.tsx`), camelCase for utilities (`client.ts`).
- **Health:** `/api/health` is the simplest possible OK probe; `/api/status` is the rich one (used by the SPA on mount).
- **Python:** 3.12+, `ruff` for linting (config in `pyproject.toml`).
- **Node:** 20+ (matches the Dockerfile build stage).

## HuggingFace Space deployment

- The HF Space's README is **generated at CI time** by `.github/workflows/sync-to-hf.yml` from the template at `.github/hf-space.README.tpl.md`. Don't hand-edit the repo's `README.md` expecting it to ship to HF — edit the template instead. The repo's `README.md` is purely for GitHub readers and is overwritten in the workflow's checkout (never pushed back to GitHub).
- **Required GitHub repo secrets** (Settings → Secrets and variables → Actions → Secrets):
  - `HF_TOKEN` — HF user access token, **write** scope.
  - `HF_USER` — HF username or org that owns the Space.
  - `HF_SPACE_NAME` — the Space's repo name (no `user/` prefix).
- **Optional GitHub repo variables** (Settings → Secrets and variables → Actions → Variables) — each falls back to a default if unset:
  - `HF_SPACE_TITLE`, `HF_SPACE_EMOJI`, `HF_COLOR_FROM`, `HF_COLOR_TO`, `HF_APP_PORT`, `HF_SHORT_DESCRIPTION`.
- **Persistent storage** lives at `/data`. It's mounted at runtime **only if** persistent storage is enabled in the Space's Settings UI. Without it, `/data` still exists and is writable, but writes are wiped on every restart. The boilerplate works in both modes.
- `/data` is **runtime-only** per HF docs — never write to `/data` from the Dockerfile (build step). Pre-create + chown is fine; writes are not.
- Do **not** use `VOLUME /data` in the Dockerfile — HF Spaces don't honor `VOLUME` declarations and it complicates layer permissions.
- Container must run as **UID 1000**. `$HOME` must be writable by that user (we set `HOME=/home/app` in the Dockerfile so libraries like `huggingface_hub` can cache to `~/.cache/huggingface`).
- **Build-time secrets** (private model downloads, etc.) use `--mount=type=secret,id=NAME` and are read from `/run/secrets/NAME` per HF docs. **Never** pass runtime secrets through `ARG` — they would bake into image layers.
- **Runtime secrets/variables** set in the HF Space Settings UI become regular env vars in the container — read them via `os.environ.get(...)` or via `pydantic-settings` (`AUTOMAITA_*` prefix for our config).
- The backend reports storage status under `storage` in `/api/status` (`exists`, `writable`, `persistent`). The `persistent` flag is a heuristic: it's `true` when a marker file from a previous startup survived to the current one.

## Out of Scope

- Auth, database, persistence, queues, LLM integrations — add per project, don't bake into the boilerplate.
- Tests — the boilerplate has nothing meaningful to test. Add tests when you add logic.
- Analytics, telemetry, error tracking — opt in per project.
- HF Hub Storage Buckets (`hf://buckets/...`) — that's a separate object-storage product accessed via `huggingface_hub`, not a filesystem mount. Not wired in by default; add the lib + auth if you need it per project.