Quick Start

Prerequisites

Tool	Version
Git	—
Python	≥ 3.12
Node.js	≥ 20.19.0
uv	latest
pnpm	≥ 10.5
just	any

Get the code

git clone https://github.com/sleep1223/fast-soy-admin.git
cd fast-soy-admin

Option A: Docker (recommended)

just docker-db-init  # first start dependencies and initialize the database
just up                                         # == docker compose up -d

Run initdb only once for a fresh database. For later updates that include model changes, run docker compose exec app uv run tortoise migrate.

Visit http://localhost:1880. Services:

• Nginx (:1880) — frontend + API reverse-proxy
• FastAPI (:9999) — backend API
• Redis (:6379) — cache

just logs      # == docker compose logs -f --tail=100
just logs app  # == docker compose logs -f --tail=100 app
just down      # == docker compose down

Option B: Local development

just install  # install backend + frontend deps
just db-init  # first-time DB init (only once)
just run      # start backend (:9999) and frontend (:9527) together; Ctrl+C to stop both

Or run them separately:

just run backend   # backend only
just run frontend  # frontend only

Default accounts

After just db-init, the seed users (password = 123456):

User	Roles
Soybean	R_SUPER
Super	R_SUPER
Admin	R_ADMIN
User	R_USER

Business demo modules are not loaded by default.

What's next

• Development guide — end-to-end CRUD module from just cli-init to deployable
• Commands reference — every just target
• Architecture — layering, RBAC, lifecycle
• Response codes — the unified business code convention

Project structure

fast-soy-admin/
├── app/                  # Backend (FastAPI)
│   ├── __init__.py       # App factory, middleware, lifespan
│   ├── core/             # Framework infrastructure
│   ├── system/           # Built-in modules (auth/users/roles/menus/...)
│   ├── business/         # Business modules (autodiscovered)
│   ├── cli/              # Code generators
│   └── utils/            # Stable import facade for business modules
├── web/                  # Frontend (Vue3 + Vite + NaiveUI)
│   └── src/
│       ├── views/        # Pages
│       ├── service/api/  # API request wrappers
│       ├── typings/api/  # TS types matching backend schemas
│       ├── locales/      # i18n (zh-CN / en-US)
│       ├── router/       # Dynamic router (server-issued)
│       ├── store/        # Pinia
│       └── hooks/        # Composables
├── deploy/               # Docker / Nginx
├── migrations/           # Tortoise migrations
├── tests/                # Backend unit tests
├── justfile              # All common commands
└── docker-compose.yml

Quality checks

just check  # full backend + frontend gate (run before pushing)

Granular:

just fmt backend         # backend ruff fix + format
just typecheck backend   # backend basedpyright
just test backend        # backend pytest
just lint frontend       # frontend eslint + oxlint
just typecheck frontend  # frontend vue-tsc
just test frontend       # frontend vitest