Metadata-Version: 2.5
Name: rafa-engineering
Version: 0.0.1b3
Summary: A self-hosted application framework for engineering web applications
Project-URL: Homepage, https://github.com/egarciamendez/rafa
Project-URL: Documentation, https://github.com/egarciamendez/rafa/tree/main/docs
Project-URL: Changelog, https://github.com/egarciamendez/rafa/blob/main/docs/changelog.md
Author: Enrique García
License: BUSL-1.1
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.100.0
Requires-Dist: packaging>=23.0
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: watchfiles>=0.21
Provides-Extra: documents
Requires-Dist: docxtpl>=0.19; extra == 'documents'
Requires-Dist: openpyxl>=3.1; extra == 'documents'
Requires-Dist: pypdf>=5.0; extra == 'documents'
Provides-Extra: maps
Requires-Dist: mapyta>=1.1; extra == 'maps'
Provides-Extra: oidc
Requires-Dist: httpx>=0.27; extra == 'oidc'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'oidc'
Provides-Extra: plotly-export
Requires-Dist: kaleido>=1.0; extra == 'plotly-export'
Requires-Dist: plotly>=6.1; extra == 'plotly-export'
Provides-Extra: plots
Requires-Dist: matplotlib>=3.8; extra == 'plots'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
Provides-Extra: screenshot
Requires-Dist: playwright>=1.49; extra == 'screenshot'
Description-Content-Type: text/markdown

# Rafa

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

<picture>
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/egarciamendez/rafa/main/docs/assets/screenshots/workspace-light.png">
  <img alt="The workspace: loads of a foundation pad on the left, its soil pressure chart on the canvas, metrics in the results panel on the right" src="https://raw.githubusercontent.com/egarciamendez/rafa/main/docs/assets/screenshots/workspace-dark.png">
</picture>

- **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 workspace 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:

```bash
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](https://github.com/egarciamendez/rafa/blob/main/docs/quickstart.md) walks from the install to your own app in the browser,
and shows how to run the [example apps](https://github.com/egarciamendez/rafa/blob/main/docs/examples/index.md) 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](https://github.com/egarciamendez/rafa/blob/main/docs/features.md).

## Documentation

| You want to | Read |
|---|---|
| Try it in 5 minutes | [Quickstart](https://github.com/egarciamendez/rafa/blob/main/docs/quickstart.md) |
| Learn the SDK step by step | [Tutorial](https://github.com/egarciamendez/rafa/blob/main/docs/tutorial/index.md) |
| Look up a term | [Concepts](https://github.com/egarciamendez/rafa/blob/main/docs/concepts.md) |
| Learn from working apps | [Example apps](https://github.com/egarciamendez/rafa/blob/main/docs/examples/index.md) |
| Solve a specific task | [How-to guides](https://github.com/egarciamendez/rafa/blob/main/docs/how-to/index.md) |
| Use the web app | [User guide](https://github.com/egarciamendez/rafa/blob/main/docs/user-guide/index.md) |
| Run or deploy the server | [Run the server](https://github.com/egarciamendez/rafa/blob/main/docs/server/index.md), [Deploy](https://github.com/egarciamendez/rafa/blob/main/docs/server/deploy.md), [Settings](https://github.com/egarciamendez/rafa/blob/main/docs/server/settings.md) |
| Call the HTTP API | [HTTP API](https://github.com/egarciamendez/rafa/blob/main/docs/reference/http-api.md) |
| Look up a class | [Reference](https://github.com/egarciamendez/rafa/blob/main/docs/reference/index.md) |
| Know why it works this way | [Decisions](https://github.com/egarciamendez/rafa/blob/main/docs/decisions.md), [Architecture](https://github.com/egarciamendez/rafa/blob/main/docs/about/architecture.md) |

Build the documentation site locally:

```bash
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

```bash
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](https://github.com/egarciamendez/rafa/blob/main/docs/contributing.md).

## License

Rafa is licensed under the [Business Source License 1.1](https://github.com/egarciamendez/rafa/blob/main/LICENSE). 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
