Rafa

Build engineering web apps in plain Python. Declare the inputs, write the calculation, get a web app with forms, live views, revisions and a database. A library you run on your own infrastructure.

• Python SDK (rafa): parametrizations, controllers, views, actions, entities, revisions, migrations. Stored in SQLite or PostgreSQL through SQLModel.
• Server: a FastAPI app that serves the HTTP API and the web UI from one process.
• Web app: a Vue 3 app rendered from layout JSON the server generates from your Python classes: entity browser, autosave with undo and revision history, RUN for slow calculations, keyboard shortcuts and a command palette, dark and light theme.

Quickstart

Requires Python 3.12+. The package contains the web app, so no Node.js is needed. Rafa is in beta:

pip install rafa-engineering                  # or: uv add rafa-engineering
rafa serve --demo                             # http://127.0.0.1:7232
rafa new bridge-checks && cd bridge-checks    # a new app of your own
rafa dev                                      # it, restarted and checked on every change

The Quickstart walks from the install to your own app in the browser, and shows how to run the example apps from a checkout.

Features

• Declarative inputs: 25 field types (numbers, options, dates, tables, dynamic arrays, files, entity references) in tabs and sections, with Lookup constraints and conditional visibility.
• Views: @view returns HTML, data, a table, an image, a PDF, a Plotly chart or 3D geometry; @metric shows a number in the results panel. Fast views refresh on every change, slow views run on RUN.
• Actions: @action methods become buttons that return a message, a file download, new input values or candidate designs to choose from.
• Entities: typed, hierarchical records with navigation, cascade rules, soft delete and recovery.
• Revisions: every save is a revision; list, read and restore.
• Schema migrations: evolve a parametrization without losing stored data.
• Server: one rafa serve command, sign-in (API key, proxy, OpenID Connect or your own hook), SQLite or PostgreSQL, backups, retention, calculation limits, a Docker image.
• Design system: one token file drives the web app's dark and light theme.

Overview: docs/features.md.

Documentation

Build the documentation site locally:

uv sync --group docs
uv run properdocs serve -f properdocs.yml   # http://127.0.0.1:8000

Project layout

src/rafa/          Python SDK (package `rafa`)
  core/            Application, Controller, Parametrization, Entity, Params, services
  fields/          input fields and layout (Tab, Section, ...)
  views/ actions/  @view, @metric, @action and their result types
  layout/          layout tree sent to the web app as JSON
  persistence/     SQLModel models and repositories
  server/          FastAPI app, settings, middleware
frontend/          Vue 3 + Vite + Tailwind web app
design_system/     design tokens (colors_and_type.css) and UI kit
examples/          example apps: engineering_app (Beam, Project, Showcase), foundation_app,
                   beam_formulas_app
docs/              documentation site (properdocs)
tests/             pytest suite

Development

uv sync --all-groups                 # Python dependencies (dev + docs)
uv run pytest                        # tests
uv run ruff check . && uv run ruff format --check .
uv run ty check .                    # type check

# Frontend development: the API with reload (answering the dev server's origin), and Vite
RAFA_CORS_ORIGINS=http://localhost:5173 \
  uv run uvicorn rafa.server.main:app --reload --port 8000 --no-proxy-headers
cd frontend
npm ci
npm run dev                          # http://localhost:5173, uses the API on :8000
npm run build                        # type check + production build to dist/
npm test                             # Storybook story tests (needs Playwright Chromium)

CI runs all of the above plus a strict docs build, and builds the wheel, installs it outside the checkout and serves an app from it. See Contributing.

License

Rafa is licensed under the Business Source License 1.1. Production use is free for:

• individuals;
• small enterprises: fewer than 50 staff and at most EUR 10 million turnover or balance sheet total (the EU definition, Recommendation 2003/361/EC, group companies included);
• teaching, study and research at educational institutions and non-profit research organizations.

Development, testing and evaluation are free for everyone. Production use on behalf of, for, or by people of a larger organization needs a commercial license: contact Enrique García at enriquegarcia@live.nl. Four years after its release, each version becomes available under the Apache License 2.0.

© 2026 Enrique García