FastapiAdmin/README.en.md

<div align="center">
     <p align="center">
          <img src="backend/data/logo.png" width="150" height="150" alt="logo" /> 
     </p>
     <h1>FastApiAdmin <img src="https://img.shields.io/badge/Version-v2.0.0-blue" alt="Version"></h1>
     <h3>Modern Full-Stack Rapid Development Platform</h3>
     <p>If you like this project, please give it a ⭐️ to show your support!</p>
     <p align="center">
          <a href="https://gitee.com/fastapiadmin/FastapiAdmin.git" target="_blank">
               <img src="https://gitee.com/fastapiadmin/FastapiAdmin/badge/star.svg?theme=dark" alt="Gitee Stars">
          </a>
          <a href="https://github.com/fastapiadmin/FastapiAdmin.git" target="_blank">
               <img src="https://img.shields.io/github/stars/fastapiadmin/FastapiAdmin?style=social" alt="GitHub Stars">
          </a>
          <a href="https://gitee.com/fastapiadmin/FastapiAdmin/blob/master/LICENSE" target="_blank">
               <img src="https://img.shields.io/badge/License-MIT-orange" alt="License">
          </a>
          <img src="https://img.shields.io/badge/Python-≥3.10-blue"> 
          <img src="https://img.shields.io/badge/NodeJS-≥20.0-blue"> 
          <img src="https://img.shields.io/badge/MySQL-≥8.0-blue"> 
          <img src="https://img.shields.io/badge/Redis-≥7.0-blue"> 
          <img src="https://img.shields.io/badge/-HTML5-E34F26?style=flat-square&logo=html5&logoColor=white"/> 
          <img src="https://img.shields.io/badge/-CSS3-1572B6?style=flat-square&logo=css3"/> 
          <img src="https://img.shields.io/badge/-JavaScript-563D7C?style=flat-square&logo=bootstrap"/> 
     </p>

English | [简体中文](./README.md)

</div>

## 📘 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** | Section **Quick Start** → **“First-time local setup (in order)”** (env files, migrations, backend + frontend) |
| **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**](backend/README.md) |
| **API docs** | After the backend is up: `http://<backend-host>/docs` (Swagger) or `/redoc` |

## 🎯 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](https://service.fastapiadmin.com/web)
- 📱 Mobile: [https://service.fastapiadmin.com/app](https://service.fastapiadmin.com/app)
- 👤 Login Account: `admin` Password: `123456`

## 🔗 Source Repositories

| Platform | Repository |
|----------|------------|
| GitHub | [FastapiAdmin Main](https://github.com/fastapiadmin/FastapiAdmin.git) \| [FastDocs Website](https://github.com/fastapiadmin/FastDocs.git) \| [FastApp Mobile](https://github.com/fastapiadmin/FastApp.git) |
| Gitee  | [FastapiAdmin Main](https://gitee.com/fastapiadmin/FastapiAdmin.git) \| [FastDocs Website](https://gitee.com/fastapiadmin/FastDocs.git) \| [FastApp Mobile](https://gitee.com/fastapiadmin/FastApp.git) |

## 📦 Engineering Structure Overview

```sh
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
```

## 🛠️ 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](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  | ![Dashboard](backend/data/dashboard.png) |
| Generator  | ![Generator](backend/data/gencode.png) |
| AI       | ![AI](backend/data/ai.png) |

### Mobile

| Login <div style="width:60px"/> | Home <div style="width:60px"/> | Profile <div style="width:60px"/> |
|----------|----------|----------|
| ![Mobile Login](backend/data/app_login.png) | ![Mobile Home](backend/data/app_home.png) | ![Mobile Personal Info](backend/data/app_mine.png) |

## 🚀 Quick Start

### First-time local setup (in order)

1. **Install runtimes**: Python ≥ 3.10, Node.js ≥ 20, [pnpm](https://pnpm.io/), 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 deps + migrations**: `cd backend`, run **`uv sync`** (recommended), then **`uv run main.py upgrade --env=dev`** to **apply the schema** (required on first run).
5. **Start backend**: `uv run main.py run --env=dev`.
6. **Frontend**: `cd frontend`, `pnpm install`, `pnpm run dev`.
7. **Browser**: use the URL printed by Vite (port from `VITE_APP_PORT` in `frontend/.env.development`); log in with the admin account (same as [Demo Environment](#-demo-environment) unless you changed seed data).

### 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

```bash
# 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`)

```bash
cd backend
uv sync
uv run main.py upgrade --env=dev
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 upgrade --env=dev` and `python main.py run --env=dev`.

#### Using pip / venv

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

### Frontend Setup

```bash
cd frontend
pnpm install
pnpm run dev
pnpm run build
```

### After startup

| Service | Notes |
|---------|--------|
| Backend API | Default often `http://127.0.0.1:8000` (check logs and `backend/env/.env.dev`) |
| Swagger | `http://<backend-host>/docs` |
| Web UI | URL printed by Vite (`VITE_APP_PORT` in `frontend/.env.development`) |

### 🐳 Docker Deployment

#### Method 1: Execute script inside project (Recommended)

```bash
# 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

```bash
# 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

```sh
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

```python
# 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

```sh
# 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

```python
# 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 Migration**: Support for Alembic database migration
- **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: Use the command `python main.py upgrade --env=dev` to apply migrations.

#### 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`). On **first run**, install dependencies and run `upgrade` migrations first—see **“First-time local setup”** above.

#### 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](https://service.fastapiadmin.com)

## 👥 Contributors

<a href="https://github.com/fastapiadmin/FastapiAdmin/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=fastapiadmin/FastapiAdmin"/>
</a>

## 🙏 Special Thanks

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

- [FastAPI](https://fastapi.tiangolo.com/)
- [Pydantic](https://docs.pydantic.dev/)
- [SQLAlchemy](https://www.sqlalchemy.org/)
- [APScheduler](https://github.com/agronholm/apscheduler)
- [Vue3](https://cn.vuejs.org/)
- [TypeScript](https://www.typescriptlang.org/)
- [Vite](https://github.com/vitejs/vite)
- [Element Plus](https://element-plus.org/)
- [UniApp](https://uniapp.dcloud.net.cn/)
- [Wot-Design-UI](https://wot-ui.cn/)

## 🎨 Community

| Group QR Code | WeChat Pay QR Code |
| --- | --- |
| ![Group QR Code](backend/data/group.jpg) | ![WeChat Pay QR Code](backend/data/wechatPay.jpg) |

## ❤️ Support the Project

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

[![Stargazers over time](https://starchart.cc/fastapiadmin/FastapiAdmin.svg?variant=adaptive)](https://starchart.cc/fastapiadmin/FastapiAdmin)