# Fluksio App

Fluksio has the goal to build a revolutionary system to tackle any sort of automation challenge.

The core of Fluksio: a node-based, test-driven automation software built to scale. This
repo holds the FastAPI backend, the flow engine, and the dashboard SPA. It is served on
`app.${DOMAIN}` (SPA) and `api.${DOMAIN}` (API); the marketing site lives in the sibling
`index` repo.

## Layout

```text
backend/        FastAPI + SQLModel + Alembic + SQLite — the `fluksio` distribution
  fluksio/flow/ the flow engine (nodes, pipeline, state backends, controller)
  fluksio/cli.py  `fluksio serve` / `enroll` / `worker`
worker/         the `fluksio-worker` distribution: the agent and the node runner
frontend/       React 19 + TanStack Router + Tailwind 4 + shadcn/ui
docs/           the public documentation site (zensical), served on docs.${DOMAIN}
docker/         compose.yml → compose.dev.yml → compose.local.yml (+ compose.traefik.yml)
scripts/        generate-client.sh, test.sh
```

## Install without Docker

```sh
pip install fluksio
fluksio serve                       # ~/.fluksio, SQLite, prints an admin password once
fluksio enroll <code> --portal https://hub.fluksio.com   # watch it from the portal
```

Nothing else has to be running. `--data-dir` puts the installation somewhere else —
worth it on a cluster, where `$HOME` is often a network filesystem SQLite cannot use.
`git` is not required but is worth having: flows are files either way, and it is what
turns each save into a commit.
The dashboard is served by the portal, so a machine with no inbound route is reached
without opening a port: it dials out.

A machine that should only *run nodes* for an engine elsewhere installs less:

```sh
pip install fluksio-worker
fluksio-worker --url wss://api.example.com/api/v1/workers/attach --token "$TOKEN" --labels gpu
```

## Getting started

Normally driven from the workspace root (`make init` once, then `make dev`). Standalone:

```sh
make install       # uv sync + bun install
make dev-utils     # proxy and mailcatcher only
make dev-backend   # FastAPI on :8000, hot reload
make dev-frontend  # Vite on :5173
```

```sh
make test           # pytest + Playwright (the e2e half needs the stack up)
make lint           # ruff + mypy + biome
make generate-client  # regenerate the frontend SDK from the OpenAPI schema
```

`make help` lists every target.

## Documentation

The public site lives in [`docs/`](docs/) and is built with zensical:

```sh
make docs-serve   # live preview on :8000
make docs         # static build into ./site
```

It is served at `docs.${DOMAIN}` by the `docs` service in `docker/compose.yml`,
and `.gitea/workflows/docs.yml` builds it with `--strict` on every push. Style
follows the root `DESIGN-GUIDELINES.md`; the tokens are mirrored in
`docs/stylesheets/extra.css`.

Repo-only material:

- [`ROADMAP.md`](ROADMAP.md) — strategy and feature record
- [`NOTEPAD.md`](NOTEPAD.md) — deferred work and findings
- [`DESIGN.md`](DESIGN.md) — points at the workspace root's `DESIGN-GUIDELINES.md`
- `docs/architecture/` in the sibling `docs` repo — the requirement sources