A complete admin panel and user portal for any FastAPI + SQLModel app — declared in Python.

Quiver is a library, not a standalone app. Mount it on your existing FastAPI application in one line, declare your CRUDs, widgets, pages and permissions in Python, and get a full admin panel (list/create/edit/delete UI, dashboard, RBAC) plus a client portal — without writing any frontend code.

🇪🇸 Este README está disponible también en español.

_{▶️ Watch the full walkthrough (with audio): assets/quiver-demo.mp4 — login, dashboard and auto-generated CRUD}

---

How it works

• Backend (fastapi-quiver, the installable package) generates REST endpoints and serves the entire UI definition (columns, fields, filters, menu, pages) from your Python declarations.
• Frontend is a generic Vite + React + TypeScript SPA that reads everything from the backend at runtime — so adding a new admin resource needs zero frontend changes.

# main.py
from fastapi import FastAPI
from quiver import QuiverApp
import permissions  # noqa: F401 — register permissions at import time

app = FastAPI()
quiver = QuiverApp(app)  # mounts auth, RBAC, users, dashboard, menu, pages and portal

---

Quick start

1. Install the backend package

pip install fastapi-quiver

_{Installing from source instead? See the installation guide.}

2. Configure the environment

SECRET_KEY and DATABASE_URL are required (see .env.example):

SECRET_KEY=change-me
DATABASE_URL=sqlite:///./app.db

3. Mount Quiver, run migrations and create the first user

quiver db migrate          # apply Quiver's auth/RBAC migrations
quiver create-superuser    # interactive first-user creation
uvicorn main:app --reload  # API served under /quiver/v1

4. Serve the admin UI

The published wheel bundles the built SPA. Mount it at the end of your setup (after registering your CRUDs) and it is served at /quiver, with the API under /quiver/v1:

quiver.serve_frontend()   # serves the admin/portal at /quiver

Open http://localhost:8000/quiver/ — no separate frontend process needed.

Developing the frontend? Run the SPA from frontend/ with hot reload instead; it serves at http://localhost:5173/quiver/ and proxies the API to your backend:

npm install
npm run dev

serve_frontend() is a no-op if no build is present, so running the SPA separately just works. The SPA base path (/quiver) is configurable via QUIVER_FRONTEND_PATH (backend) and VITE_BASE_PATH (frontend) — keep them in sync.

---

Documentation

Document	Contents
Installation	Install the backend, configure env vars, set up the frontend
Quick start	First CRUD, first widget — a working app in 20 minutes
CRUD engine	Fields, columns, filters, lifecycle hooks, permissions
Dashboard	StatCards, charts, per-widget permissions
Roles & permissions	Defining permissions, creating roles, protecting routes
Menu	Structure of the admin sidebar
Custom pages	Arbitrary React pages in the admin or portal
User portal	Client portal: access roles, customization
Frontend	Design tokens, components, layouts
Examples	Ready-to-run reference projects

Spanish versions of these guides live under docs/es/.

---

Example app

examples/almacen/ is a complete reference host app (warehouse management): 4 interconnected CRUDs, stock movements with business logic, dashboard widgets, custom permissions and a custom page. It is the best place to see how a consumer wires everything up.

---

Requirements

• Python 3.11+
• Node.js 18+ (for the frontend only)
• PostgreSQL or SQLite (for development)
• An existing FastAPI project using SQLModel as its ORM

---

What Quiver gives you

• Full authentication — login, JWT access/refresh tokens, password reset by email
• Automatic CRUD — declare a SQLModel model and get list/create/edit/delete with UI included
• Dashboard — configurable StatCards and charts backed by your database
• Roles & permissions — granular RBAC, assigned from the UI
• User portal — a separate area for your clients, with its own roles
• Custom pages — drop your own React pages into the admin or portal
• Configurable menu — structure the sidebar with groups, items and permission control
• Internationalization — English/Spanish UI out of the box (react-i18next) with a language switcher; auto-detects the browser language and is easy to extend with new locales

---

Screenshots

Dashboard	Auto-generated CRUD list
Auto-generated form	Login

_{Screenshots from the examples/almacen reference app.}

---

Contributing

Contributions are welcome — see CONTRIBUTING.md.

License

MIT © rnkr69