fastapi-react-admin

English | 简体中文

A batteries-included admin foundation · FastAPI + React 19 + shadcn/ui

Row-level permissions · multi-tab that keeps state · approval workflow · an AI assistant that can't overreach · S3 storage with resumable uploads · web, desktop and mobile

Live demo · Docs · DeepWiki project guide · Quick start · Features · Releases

🚀 Demo account admin / 123456 — a public instance anyone can log into; data may be changed or wiped by other visitors, so don't store anything real.

One rewrite, distilled into a base you can start writing business logic on.

AI has made writing code faster, and there are more systems to build because of it: small tools that never made the roadmap are now worth doing, and systems that have run for years are due for a replacement. Yet the first weeks of every new system go to the same list — login, permissions, org structure, approvals, files, notifications.

This project started as a rewrite of a few small Java + Vue 2 systems at work. Rather than patch the old architecture, we rebuilt them on FastAPI + React 19 and distilled everything that gets rebuilt every time into a base. The next system starts with business logic.

The backend, the web admin console, a desktop template, a mobile template and the docs site live in one pnpm + turbo monorepo: install once, and one pnpm dev starts backend and frontend.

apps/
├── api        backend · FastAPI + Celery
├── web        web admin console · React 19
├── desktop    desktop template · Electron
├── mobile     mobile template · Expo / React Native
└── docs       docs site · Astro
packages/      one-way deps: i18n / api ← ui ← platform ← web
├── api        frontend/backend type contract, generated from OpenAPI
├── i18n       Chinese / English strings
├── ui         component library, no business logic, portable as a whole
└── platform   permissions, multi-tab, business pages

• The web admin console is the core, ready to use
• The desktop template loads the web build and only adds what a browser can't do: silent printing, local hardware, auto-update
• The mobile template has native screens and shares the API types and translations with web
• The layering is enforced: dependencies flow one way, and pnpm arch:check checks it in CI

AI changes code fast, so every change needs something to catch it:

• Tests — 1,600+ tests against a real database and a real browser, no mocks, on every CI run; the E2E report is public
• Types — the frontend/backend contract is generated from OpenAPI; mobile infers every request's types from it, so an API change the screens didn't follow fails type checking (the web client is still migrating, and its call sites currently declare response types by hand)
• Rules written for AI — 50+ per-directory CLAUDE.md / AGENTS.md files record pitfalls found by testing; a coding assistant reads the one for whatever directory it edits
• A backend inside the AI ecosystem — Python + FastAPI, with the built-in AI assistant on pydantic-ai

• Permissions down to which rows you see — beyond menus and buttons there are data scopes: on the same user table, a department manager only sees their own department. Rules live on model columns, and the UI warns you when a rule is misconfigured
• Tabs that keep their state — built on React 19's <Activity>: a half-filled form, the page you were on, an expanded tree are all still there when you switch back; view state lives in the URL, so a refresh doesn't lose it either
• Approval workflow out of the box — a Feishu-style form designer and flow tree, with or-sign / co-sign, send back, add approvers, take back and timeouts
• An AI assistant that can't overreach — it can do exactly what the signed-in user can do; write actions are previewed and only run after the user confirms, and every call is audited. External systems can reach the same tools through an MCP gateway
• Large files, handled — local disk or S3-compatible storage, instant upload by hash, parallel chunks, resume after a page refresh, and one upload tray for everything in flight
• Pick your database — PostgreSQL, SQL Server or MySQL, same code
• Beyond the browser — an Electron desktop app (installers for three platforms with auto-update) and a native mobile app
• Tested for real — 1,600+ tests against real databases and a real browser; CI runs the full backend suite on both PostgreSQL and SQL Server

The Expo app covers the things people actually do on a phone (#224); admin-console modules stay on the web. It is versioned separately from the web app.

• Has: home (my approvals · to-do) · approvals (to-do / done / CC'd / started by me · approve / reject / send back / transfer / add signer · start a request · drafts · resubmit after send-back · restart a closed request) · notices · notifications · users · profile (bind a phone number) · server monitoring · time zone · SMS code sign-in · two-factor sign-in · session expiry reasons
• Web only, by design: roles / departments / menus · files · operation & sign-in logs · turning on two-factor auth · AI form filling and AI pre-review in approvals
• Not yet verified: no automated tests (#137), most screens only run on an emulator, no release pipeline

Switch with DATABASE_TYPE in .env — same code, same migration chain, seed data for all three.

You need Node ≥ 22.13, Python ≥ 3.11, uv and Docker.

docker compose -f docker-compose.dev.yml up -d          # PostgreSQL + Redis
pnpm install:all                                        # frontend + backend dependencies
cp apps/api/backend/.env.example apps/api/backend/.env  # defaults match the containers above
pnpm db:init                                            # create tables + seed data (first run)
pnpm dev                                                # open http://127.0.0.1:8888

Sign in as admin with the password you set during pnpm db:init. Switching to SQL Server / MySQL, S3, skipping the captcha and running tests are covered in CONTRIBUTING.md (Chinese; the commands are language-independent).

1,400+ backend pytest tests run against a real database and Redis; 150+ Playwright tests drive a real browser against the real API and database — no mocks. Data permissions were verified by signing in as 41 real accounts one by one; key safeguards are mutation-tested (break the code on purpose, confirm the tests go red). The E2E report from every main run is public, with screenshots and videos of failures.

MIT

The backend was originally built on fastapi-best-architecture (FBA) — its three-layer structure, plugin system and RBAC / data-scope model come from FBA's design. Thanks to its author and contributors 🙏 FBA is also MIT-licensed; its original copyright notice is kept in apps/api/LICENSE. Thanks also to shadcn/ui, TanStack, Tiptap, file-viewer and the other open-source projects this is built on.