Rio Boilerplate

Production-ready Rio web application template featuring session-based authentication, optional TOTP multi-factor security, FastAPI endpoints, and a reusable component library.

Highlights

• Auth & security: login, password reset, role-based guards, MFA toggles, recovery codes, admin-only operations.
• API layer: FastAPI routers for profile data, shared validation in app/app/validation.py, persistence helpers for SQLite.
• UI experience: Rio pages for public marketing routes and protected app area, shared layout elements, and Plotly chart support.
• Built-in primary currency system with configurable naming, precision, admin tooling, and ledger history.
• Developer ergonomics: Example scripts, bundled Rio documentation, and deployment playbooks for quick onboarding.

Using as a Template

There are two ways to use this boilerplate:

Option A: Clone (simple, no upstream updates)

git clone git@github.com:azidancorp/RioBoilerplate.git my-project
cd my-project
rm -rf .git && git init  # Start fresh git history

Option B: Add as Remote (recommended - enables upstream updates)

If you already have a git project and want to pull in this boilerplate while keeping the ability to get future updates:

# From your existing project directory
git remote add boilerplate git@github.com:azidancorp/RioBoilerplate.git
git fetch boilerplate
git merge boilerplate/main --allow-unrelated-histories -m "Merge RioBoilerplate template"

This merges the boilerplate into your project. Later, to pull updates:

git fetch boilerplate
git merge boilerplate/main

For detailed merge instructions and conflict resolution, see UPSTREAM_MERGE_GUIDE.md.

Quick Start

1. Set up the boilerplate using Option A or B above.
2. Create and activate a virtual environment: python -m venv venv then source venv/bin/activate (or venv\Scripts\activate on Windows).
3. Install dependencies: pip install -r requirements.txt.
4. Copy .env.example to .env and set any provider/session secrets your deployment uses.
5. From the repository root, initialize the first verified root account: cd app && python -m app.scripts.bootstrap_root.
6. Still in app/, start the development server: rio run.
7. The app stores its local SQLite database at app/app/data/app.db. This file is ignored by git and should remain a local runtime artifact.

Access the dev server at http://localhost:8000. Use rio run --port 8000 --release to mirror production settings. Replace 8000 with the port you actually chose when checking a different local run.

Public password signup and OAuth registration cannot initialize an empty database. With no arguments, bootstrap_root prompts for email and password. You can also pass values directly, for example python -m app.scripts.bootstrap_root --email owner@example.com --password '<strong-password>'. --username owner is optional; if you provide --username without --email, that username becomes the root login identifier. The command creates one verified root user only when the database is empty.

Railway First Deployment

Warning: not production-ready on Railway yet. As shipped, railway.toml deploys with no volume attached, and Railway's container filesystem is ephemeral — the SQLite database is erased on every deploy and restart. Do not put real users on a Railway deployment until the runtime-data relocation described below is complete and a volume is mounted. The supported production path today is the VPS guide in DEPLOYMENT_INSTRUCTIONS.md; the outstanding Railway work and the root-bootstrap procedure are tracked in docs/railway-readiness.md.

railway.toml runs strict prestart checks before starting the public server. On a fresh database, the deployment exits with a bootstrap error rather than exposing an unclaimed root slot. This fail-closed result is expected.

Do not expose a Railway domain until the initial root has been created against the same persistent database the service will use. railway run and railway shell execute locally with Railway variables and do not modify the deployed SQLite volume.

The current app/app/data/ directory mixes mutable runtime state with tracked sample data, so it does not yet have a safe Railway volume mount target. Complete the runtime-data relocation tracked in docs/railway-readiness.md before treating this SQLite configuration as Railway-ready; mounting a volume over the whole directory would hide tracked application files.

Everyday Development

• rio run – hot-reloading dev server.
• rio run --port 8000 --release – release-mode smoke test.
• curl -fsS http://127.0.0.1:8000/api/health – machine-readable health check for the running app and local SQLite schema.

Configuration

• .env is for secrets only, such as SESSION_SECRET_KEY or provider credentials.
• Non-secret behavior stays code-configured in app/app/config.py. Edit that file directly for app-specific defaults such as email validation, username login, password policy, and currency naming/precision.
• Email validation and username-login behavior are documented in docs/configuration/email-validation.md.
• Root initialization is intentionally not configurable: public registration never assigns a privileged role.
• The runtime SQLite database file app/app/data/app.db is created locally on first run and is ignored by git.
• Before going to production, replace the placeholder branding in app/app/assets/ (favicon.ico, logo.png, og_image.png) with your own. The source script at app/assets_src/build_brand_assets.py shows how they were generated and can be adapted; run it from the outer app/ directory with python assets_src/build_brand_assets.py.

Currency System

• SQLite schema stores a single minor-unit balance per user plus an audited user_currency_ledger.
• Admin UI (/app/admin) now surfaces balances, allows grants/deductions, and shows success/error feedback.
• FastAPI endpoints (/api/currency/*) expose balance, ledger, and privileged adjustment APIs.
• CLI helper python app/app/scripts/currency_admin.py supports list, ledger, adjust, and set operations from the terminal.

Project Layout

RioBoilerplate/
├── app/
│   ├── rio.toml               # Rio app configuration
│   ├── JSPages/               # Prototype HTML/JS demos
│   └── app/
│       ├── __init__.py        # App bootstrap + FastAPI bridge
│       ├── api/               # FastAPI routers (profiles, examples)
│       ├── assets/            # Branding assets (favicon, logo, og_image) — replace before production
│       ├── components/        # Reusable Rio UI widgets
│       ├── data/              # Runtime SQLite DB (local/ignored) and sample data
│       ├── pages/             # Public pages
│       │   └── app_page/      # Protected app pages
│       ├── scripts/           # Utilities and MFA helper scripts
│       ├── permissions.py     # Role checks and guard helpers
│       ├── persistence.py     # Database access layer
│       └── validation.py      # Input validation & Pydantic models
├── RioDocumentation/          # Bundled Rio reference material
├── DEPLOYMENT_INSTRUCTIONS.md # Production rollout guide
├── requirements.txt
└── README.md

Testing & QA

Focus release verification on:

• Registration, login, and role-based routing.
• Enabling/disabling MFA and using recovery codes.
• Profile update via the UI and profile CRUD via /api/profiles.
• Error handling across contact flows and API responses.
• Currency adjustments: verify admin operations, ledger history, and /api/currency/* behaviour (positive & negative paths).
• Release health check: curl -fsS http://127.0.0.1:8000/api/health against the port used for that run.

Further Reading

• AGENTS.md – contributor workflow and coding standards.
• CLAUDE.md – extended architecture and assistant notes.
• DEPLOYMENT_INSTRUCTIONS.md – step-by-step deployment guidance.
• RioDocumentation/ – offline Rio framework reference.

License

Distributed under the terms of the included LICENSE.