FastapiAdmin/README.en.md

FastApiAdmin

Modern Full-Stack Rapid Development Platform

If you like this project, please give it a ⭐️ to show your support!

English | 简体中文

📘 Project Introduction

FastApiAdmin is a completely open-source, highly modular, and technologically advanced modern rapid development platform designed to help developers efficiently build high-quality enterprise-level backend and frontend systems. This project adopts a frontend-backend separation architecture, integrating the Python backend framework FastAPI and the mainstream frontend framework Vue3 to achieve unified development across multiple terminals, providing a one-stop out-of-the-box development experience.

Design Philosophy: With modularity and loose coupling at its core, it pursues rich functional modules, simple and easy-to-use interfaces, detailed development documentation, and convenient maintenance methods. By unifying frameworks and components, it reduces the cost of technology selection, follows development specifications and design patterns, builds a powerful code hierarchical model, and comes with comprehensive local language support. It is specifically tailored for team and enterprise development scenarios.

📖 Start Here (New Users)

I want to…	Go to
Run the project locally ASAP	Quick Start → “First-time local setup (in order)” (env, deps, run; first backend start auto-inits DB schema & seed data)
Architecture diagram & default ports (5180 / 8001, …)	“Local Architecture & Default Ports” (matches .env*.example)
See what the project offers	Built-in Functional Modules, Demo Environment (credentials)
Extend / plugin development	Secondary Development Tutorial; backend layout and CLI: backend/README.md
API docs	With template env: http://127.0.0.1:8001/docs (see SERVER_PORT)

🎯 Core Advantages

Advantage	Description
🔥 Modern Tech Stack	Built with cutting-edge technologies like FastAPI + Vue3 + TypeScript
⚡ High Performance	Leveraging FastAPI's asynchronous features and Redis caching for optimized response speed
🔐 Secure & Reliable	JWT + OAuth2 authentication mechanism with RBAC permission control model
🧱 Modular Design	Highly decoupled system architecture for easy expansion and maintenance
🌐 Full-Stack Support	Integrated solution for Web + Mobile(H5) + Backend
🚀 Rapid Deployment	One-click Docker deployment for quick production rollout
📖 Comprehensive Docs	Detailed documentation and tutorials to reduce learning curve
🤖 Intelligent Agent Framework	Based on Langchain and Langgraph, develop intelligent agents

🍪 Demo Environment

• 💻 Web: https://service.fastapiadmin.com/web
• 📱 Mobile: https://service.fastapiadmin.com/app
• 👤 Login Account: admin Password: 123456

🔗 Source Repositories

Platform	Repository
GitHub	FastapiAdmin Main | FastDocs Website | FastApp Mobile
Gitee	FastapiAdmin Main | FastDocs Website | FastApp Mobile

📦 Engineering Structure Overview

FastapiAdmin
├─ backend               # Backend project (FastAPI + Python)
├─ frontend              # Web frontend project (Vue3 + Element Plus)
├─ devops                # Deployment configurations
├─ docker-compose.yaml   # Docker orchestration file
├─ deploy.sh             # One-click deployment script
├─ LICENSE               # Open source license
|─ README.en.md          # English documentation
└─ README.md             # Chinese documentation

🏗️ Local Architecture & Default Ports

Aligned with backend/env/.env.dev.example and frontend/.env.development.example; if you changed .env.dev / .env.development, use your local values.

flowchart LR
  subgraph client[Browser]
    U[User]
  end
  subgraph fe[frontend dev]
    V[Vue3 + Vite]
  end
  subgraph be[backend]
    A[FastAPI / Uvicorn]
  end
  subgraph data[Data]
    DB[(Database)]
    R[(Redis)]
  end
  U --> V
  V -->|REST via VITE_API_BASE_URL| A
  A --> DB
  A --> R

Component	Config key	Example default (dev template)
Web UI	frontend/.env.development → VITE_APP_PORT	5180 → http://127.0.0.1:5180
Backend HTTP	backend/env/.env.dev → SERVER_HOST / SERVER_PORT	0.0.0.0:8001 → http://127.0.0.1:8001
API base URL	VITE_API_BASE_URL	http://127.0.0.1:8001
API prefix	ROOT_PATH + VITE_APP_BASE_API	/api/v1 on both sides
Swagger / Redoc	—	http://127.0.0.1:8001/docs, /redoc
WebSocket (optional)	VITE_APP_WS_ENDPOINT	e.g. ws://127.0.0.1:8001
DB port	DATABASE_PORT	Template uses MySQL 3306; PostgreSQL often 5432
Redis	REDIS_HOST / REDIS_PORT	Example localhost:6379

🛠️ Technology Stack Overview

Type	Technology Selection	Description
Backend Framework	FastAPI / Uvicorn / Pydantic 2.0 / Alembic	Modern, high-performance asynchronous framework with mandatory type constraints and data migration capabilities
ORM	SQLAlchemy 2.0	Powerful ORM library
Scheduled Tasks	APScheduler	Easily implement scheduled tasks
Authentication	PyJWT	Implement JWT authentication
Frontend Framework	Vue3 / Vite5 / Pinia / TypeScript	Rapidly develop Vue3 applications
Web UI	ElementPlus	Enterprise-level UI component library
Mobile	UniApp / Wot Design Uni	Cross-platform mobile application framework
Database	MySQL / PostgreSQL / Sqlite	Support for relational and document databases
Cache	Redis	High-performance cache database
Documentation	Swagger / Redoc	Automatically generate API documentation
Deployment	Docker / Nginx / Docker Compose	Containerized deployment solution
Intelligent Agent Framework	Langchain / Langgraph	Intelligent agent framework based on Langchain and Langgraph

📐 Backend Conventions (Dates & Serialization)

With Pydantic v2 and PostgreSQL (asyncpg), ORM writes expect native Python date/time types; JSON responses need serializable strings. The project uses PlainSerializer(..., when_used='json') on DateStr / TimeStr / DateTimeStr in backend/app/core/validator.py; unified responses use jsonable_encoder in backend/app/common/response.py; when writing to Redis, use model_dump(mode='json') before json.dumps. See backend/README.md for alignment with the root README.

📌 Built-in Functional Modules

Module	Features	Description
📊 Dashboard	Workbench, Analysis Page	System overview and data analysis
⚙️ System Management	Users, Roles, Menus, Departments, Positions, Dictionaries, Configurations, Announcements	Core system management functions
👀 Monitoring	Online Users, Server Monitoring, Cache Monitoring	System runtime status monitoring
📋 Task Management	Scheduled Tasks	Asynchronous task scheduling management
📝 Log Management	Operation Logs	User behavior auditing
🧰 Development Tools	Code Generation, Form Builder, API Documentation	Tools to enhance development efficiency
📁 File Management	File Storage	Unified file management

🔧 Models

Module	Screenshot
Dashboard
Generator
AI

Mobile

Login	Home	Profile

🚀 Quick Start

First-time local setup (in order)

1. Install runtimes: Python ≥ 3.10, Node.js ≥ 20, pnpm, local MySQL or PostgreSQL (or SQLite if configured in backend/env/.env.dev), and Redis matching your .env.dev.
2. Clone the repo: see “Get the Code” below.
3. Env files: copy backend/env/.env.dev.example → backend/env/.env.dev, and frontend/.env.development.example → frontend/.env.development; fill in DB, Redis, JWT secret, etc. Create an empty database first.
4. Backend dependencies: cd backend, run uv sync (recommended) or pip install -r requirements.txt.
5. Start backend: uv run main.py run --env=dev. The first start automatically initializes tables and seed data—you usually do not need to run upgrade first.
6. Frontend: cd frontend, pnpm install, pnpm run dev.
7. Browser: with the template env, open http://127.0.0.1:5180 (VITE_APP_PORT=5180); log in with the admin account (same as Demo Environment unless you changed seed data).

Use revision / upgrade only when you change ORM models and manage migrations with Alembic (see FAQ below).

Environment Requirements

Type	Technology Stack	Version
Backend	Python	≥ 3.10 (3.12 recommended)
Backend	FastAPI	0.109+
Frontend	Node.js	≥ 20.0
Frontend	Vue3	3.3+
Database	MySQL / PostgreSQL / SQLite	As in backend/env
Cache	Redis	6.x / 7.x (match .env)

Get the Code

# Clone the repository to your local machine
git clone https://gitee.com/fastapiadmin/FastapiAdmin.git
# Or
git clone https://github.com/fastapiadmin/FastapiAdmin.git

Backend Note: After cloning the code, you need to rename the .env.dev.example file in the backend/env directory to .env.dev, and rename the .env.prod.example file in the backend/env directory to .env.prod. Then modify the database connection information, Redis connection information, etc., according to the actual situation.

Frontend Note: After cloning the code, you need to rename the .env.development.example file in the frontend directory to .env.development, and rename the .env.production.example file in the frontend directory to .env.production. Then modify the interface address, etc., according to the actual situation.

Backend Setup

Using uv (recommended, matches backend/pyproject.toml)

cd backend
uv sync
# First start auto-inits schema & data; no need to run upgrade beforehand
uv run main.py run --env=dev
# uv run main.py run --env=prod

Without uv: pip install -r requirements.txt, then python main.py run --env=dev. Use upgrade when you need Alembic after model changes.

Using pip / venv

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python main.py run --env=dev

Frontend Setup

cd frontend
pnpm install
pnpm run dev
pnpm run build

After startup

When using .env.dev.example / .env.development.example as-is:

Service	URL (example)
Web UI (Vite)	http://127.0.0.1:5180
Backend base	http://127.0.0.1:8001
Swagger	http://127.0.0.1:8001/docs
API prefix	http://127.0.0.1:8001/api/v1 (matches ROOT_PATH)

🐳 Docker Deployment

Method 1: Execute script inside project (Recommended)

# 1. Clone the repository to server
git clone https://gitee.com/fastapiadmin/FastapiAdmin.git
cd FastapiAdmin

# 2. Grant execution permissions and deploy
chmod +x deploy.sh
./deploy.sh

# View container logs
./deploy.sh logs

# Stop services
./deploy.sh stop

Method 2: Execute script outside project

# 1. Copy the deployment script to server
cp deploy.sh /home/
cd /home
chmod +x deploy.sh

# 2. Execute one-click deployment (will auto clone project)
./deploy.sh

# View container logs
./deploy.sh logs

# Stop services
./deploy.sh stop

# Restart services
./deploy.sh restart

# Update code and restart (without rebuilding images, suitable for backend hot update)
./deploy.sh update

Note

:

• First deployment will automatically pull code and build images
• Frontend uses locally built dist directory, please build locally and commit to repository if you need to update frontend
• Ensure devops/nginx/ssl/ directory contains SSL certificate files (if using HTTPS)

🛠️ Secondary Development Tutorial

Backend Development

The project adopts a plugin-based architecture design, and it is recommended to carry out secondary development in the backend/app/plugin directory. The system will automatically discover and register all routes that meet the specifications, facilitating module management and upgrade maintenance.

Plugin Architecture Features

• Automatic Route Discovery: The system automatically scans all controller.py files in the backend/app/plugin/ directory
• Automatic Route Registration: All routes are automatically registered to the corresponding prefix path (module_xxx -> /xxx)
• Modular Management: Code is organized by functional modules for easy maintenance and extension
• Support for Multi-level Nesting: Support for multi-level nested structures within modules

Plugin Directory Structure

backend/app/plugin/
├── module_application/  # Application module (automatically mapped to /application)
│   └── ai/              # AI submodule
│       ├── controller.py # Controller file
│       ├── model.py      # Data model file
│       ├── schema.py     # Data validation file
│       ├── service.py    # Business logic file
│       └── crud.py       # Data access file
├── module_example/      # Example module (automatically mapped to /example)
│   └── demo/            # Submodule
│       ├── controller.py # Controller file
│       ├── model.py      # Data model file
│       ├── schema.py     # Data validation file
│       ├── service.py    # Business logic file
│       └── crud.py       # Data access file
├── module_generator/    # Code generation module (automatically mapped to /generator)
└── init_app.py          # Plugin initialization file

Automatic Route Registration Mechanism

The system will automatically discover and register all routes that meet the following conditions:

1. Controller files must be named controller.py
2. Routes are automatically mapped: module_xxx -> /xxx
3. Support for multiple APIRouter instances
4. Automatic route deduplication

Secondary Development Steps

1. Create Plugin Module: Create a new module directory under backend/app/plugin/, such as module_yourfeature
2. Write Data Model: Define database models in model.py
3. Write Data Validation: Define data validation models in schema.py
4. Write Data Access Layer: Write database operation logic in crud.py
5. Write Business Logic Layer: Write business logic in service.py
6. Write Controller: Define routes and handling functions in controller.py
7. Automatic Registration: The system automatically scans and registers all routes, no manual configuration required

Controller Example

# backend/app/plugin/module_yourfeature/yourcontroller/controller.py
from fastapi import APIRouter, Depends, Path
from fastapi.responses import JSONResponse

from app.common.response import SuccessResponse
from app.core.router_class import OperationLogRoute
from app.core.dependencies import AuthPermission
from app.api.v1.module_system.auth.schema import AuthSchema
from .service import YourFeatureService

# Create route instance
YourFeatureRouter = APIRouter(
    route_class=OperationLogRoute, 
    prefix="/yourcontroller", 
    tags=["Your Feature Module"]
)

@YourFeatureRouter.get("/detail/{id}", summary="Get Detail")
async def get_detail(
    id: int = Path(..., description="Feature ID"),
    auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:detail"]))
) -> JSONResponse:
    """
    Get feature detail
    
    Parameters:
    - id (int): Feature ID
    - auth (AuthSchema): Authentication information model
    
    Returns:
    - JSONResponse: JSON response containing feature detail
    """
    result = await YourFeatureService.detail_service(id=id, auth=auth)
    return SuccessResponse(data=result)

@YourFeatureRouter.get("/list", summary="Get List")
async def get_list(
    auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:list"]))
) -> JSONResponse:
    """
    Get feature list
    
    Parameters:
    - auth (AuthSchema): Authentication information model
    
    Returns:
    - JSONResponse: JSON response containing feature list
    """
    result = await YourFeatureService.list_service(auth=auth)
    return SuccessResponse(data=result)

Development Specifications

1. Naming Convention: Module names use module_xxx format, controller names use camelCase naming
2. Permission Control: All API interfaces must add permission control decorators
3. Log Recording: Use OperationLogRoute class to automatically record operation logs
4. Return Format: Use SuccessResponse or ErrorResponse uniformly for responses
5. Code Comments: Add detailed docstrings for all API interfaces

Notes

• Plugin module names must start with module_
• Controller files must be named controller.py
• Routes are automatically mapped to corresponding prefix paths
• No manual route registration required, the system automatically discovers and registers

Frontend Part

1. Configure Frontend API: Create corresponding API files in frontend/src/api/ directory
2. Write Page Components: Create page components in frontend/src/views/ directory
3. Register Routes: Register routes in frontend/src/router/index.ts

Code Generator Usage

The project has a built-in code generator that can automatically generate front-end and back-end code based on database table structures, greatly improving development efficiency.

Generation Steps

1. Login System: Login to the system using an administrator account
2. Enter Code Generation Module: Click "Code Generation" in the left menu
3. Import Table Structure: Select the database table to generate code for
4. Configure Generation Parameters: Fill in module name, function name, etc.
5. Generate Code: Click the "Generate Code" button
6. Download or Write: Choose to download the code package or write directly to the project directory

Generated File Structure

# Backend files
backend/app/plugin/module_yourmodule/
└── yourfeature/
    ├── controller.py # Controller file
    ├── model.py      # Data model file
    ├── schema.py     # Data validation file
    ├── service.py    # Business logic file
    └── crud.py       # Data access file

# Frontend files
frontend/src/
├── api/module_yourmodule/
│   └── yourfeature.ts # API call file
└── views/module_yourmodule/
    └── yourfeature/
        └── index.vue # Page component

Generated Code Example

# Generated controller code example
from fastapi import APIRouter, Depends
from fastapi.responses import JSONResponse

from app.common.response import SuccessResponse
from app.core.router_class import OperationLogRoute
from app.core.dependencies import AuthPermission
from app.api.v1.module_system.auth.schema import AuthSchema
from .service import YourFeatureService
from .schema import (
    YourFeatureCreateSchema,
    YourFeatureUpdateSchema,
    YourFeatureQueryParam
)

YourFeatureRouter = APIRouter(
    route_class=OperationLogRoute, 
    prefix="/yourfeature", 
    tags=["Your Feature Module"]
)

@YourFeatureRouter.get("/detail/{id}")
async def get_detail(
    id: int, 
    auth: AuthSchema = Depends(AuthPermission(["module_yourmodule:yourfeature:detail"]))
) -> JSONResponse:
    result = await YourFeatureService.detail_service(id=id, auth=auth)
    return SuccessResponse(data=result)

Development Tools

• Code Generator: Automatically generate front-end and back-end CRUD code
• API Documentation: Automatically generate Swagger/Redoc API documentation
• Database: Auto schema & seed on first start; Alembic supported for schema evolution
• Log System: Built-in log recording and query functions
• Monitoring System: Built-in server monitoring and cache monitoring functions

Development Process

1. Requirement Analysis: Clarify functional requirements and business logic
2. Database Design: Design database table structure
3. Code Generation: Use code generator to generate basic code
4. Business Logic Development: Perfect business logic and interfaces
5. Frontend Development: Develop frontend pages and interactions
6. Testing: Conduct unit testing and integration testing
7. Deployment: Deploy to production environment

Development Notes

1. Permission Control: All API interfaces must add permission control
2. Data Validation: All input data must be validated
3. Exception Handling: Uniformly handle API exceptions
4. Log Recording: Key operations must be logged
5. Performance Optimization: Pay attention to API performance optimization, avoid slow queries
6. Code Specification: Follow PEP8 and project code specifications

Common Questions

Q: How to add a new functional module?

A: Follow the secondary development steps, create a new module directory under backend/app/plugin/ directory, and write related code.

Q: How to configure the database?

A: Configure database connection information in backend/env/.env.dev or backend/env/.env.prod files.

Q: How to configure Redis?

A: Configure Redis connection information in backend/env/.env.dev or backend/env/.env.prod files.

Q: How to generate database migration files?

A: Use the command python main.py revision --env=dev to generate migration files.

Q: How to apply database migrations?

A: Run python main.py upgrade --env=dev (or uv run ...) when you need Alembic migrations. First start usually does not require this—the app initializes automatically.

Q: How to start the development server?

A: From backend, run uv run main.py run --env=dev (or python main.py run --env=dev). First start auto-initializes the database and seed data; no manual upgrade is required beforehand.

Q: Do I need to run migrations before the first start?

A: Usually no. The first backend start initializes schema and data. Use revision / upgrade only when you change models and use Alembic.

Q: How to build the frontend production version?

A: Use the command pnpm run build to build the frontend production version.

Q: How to deploy to production environment?

A: Use the ./deploy.sh script for one-click deployment to production environment.

ℹ️ Help

For more details, please check the Official Documentation

👥 Contributors

🙏 Special Thanks

Thanks to the contributions and support of the following open-source projects:

• FastAPI
• Pydantic
• SQLAlchemy
• APScheduler
• Vue3
• TypeScript
• Vite
• Element Plus
• UniApp
• Wot-Design-UI

🎨 Community

Group QR Code	WeChat Pay QR Code

❤️ Support the Project

If you like this project, please give it a ⭐️ Star to show your support! Thank you very much!