Build a Python Study‑Room Reservation System in 20 Minutes with Cursor AI – FastAPI Backend & Vue 3 Frontend

Project Overview

The system is a front‑end/back‑end separated online reservation platform for study rooms in a university setting. Administrators maintain rooms and seats, while students select rooms, visualize seat maps, reserve time slots, check‑in, and cancel reservations. Additional functions include announcements, feedback, and statistical dashboards.

Roles and Permissions

Administrator (admin) – system operator; can perform CRUD on users, rooms, and seats, manage reservations globally, publish announcements, handle feedback, and view statistics.

Student (student) – regular user; can reserve rooms, view/check‑in/cancel own reservations, browse announcements, submit feedback, and manage personal profile.

After login the route is split by role: / for the admin dashboard and /portal for the student portal.

Core Business Modules

User Management – account CRUD, role assignment, enable/disable, credit score maintenance.

Study‑Room Management – name, location, capacity, opening hours, cover image, status.

Seat Management – seat numbers per room, status available or disabled.

Reservation Management (core) – seat‑level reservation with time‑slot conflict validation, check‑in, cancellation.

Announcement Management – publish/draft system notices.

Feedback – students submit feedback; admins reply (status pending / replied).

Data Statistics – ECharts visualizes reservation trends, status distribution, room usage.

Reservation Status Flow

reserved

– booked, awaiting check‑in. checked_in – checked in. completed – completed. cancelled – cancelled.

Reservation Creation Rules

Seat must exist and be available.

Start time must be earlier than end time.

For the same seat and date, the new time slot must not overlap existing reserved or checked_in reservations.

Technology Stack

Overall Architecture

Classic B/S three‑layer architecture: Presentation layer (Vue 3) → Business logic layer (FastAPI) → Data access layer (SQLAlchemy + MySQL).

Backend Technologies

FastAPI 0.115 – web framework, RESTful API.

Uvicorn – ASGI server.

SQLAlchemy 2.0 – ORM, object‑table mapping.

PyMySQL – MySQL driver.

python‑jose – JWT generation & parsing.

Pydantic – request/response model validation.

python‑multipart – file upload handling.

Frontend Technologies

Vue 3 – progressive front‑end framework.

Vite 6 – build tool & dev server.

Vue Router 4 – routing & navigation guards.

Pinia – state management (token, user info).

Element Plus – UI component library.

Axios – HTTP requests.

ECharts 5 – data visualization charts.

Day.js – date formatting.

Database

Database name: db_studyroom.

MySQL 8, default port 3308 .

All tables prefixed with t_.

System Architecture

Project Directory Structure

sys13/
├── client/                 # Vue3 front‑end
│   ├── src/
│   │   ├── views/          # Pages (admin & student)
│   │   ├── layout/          # MainLayout / StudentLayout
│   │   ├── router/          # Routes & guards
│   │   ├── store/           # Pinia user state
│   │   └── utils/           # request, date utilities
│   └── vite.config.js      # Proxy /api → 8000
├── server/                 # FastAPI back‑end
│   ├── main.py             # App entry, CORS, route registration
│   ├── sql/init.sql        # Table creation & test data
│   └── app/
│       ├── api/           # Business API routes
│       ├── core/          # Config, security, DI
│       ├── db/            # DB connection & session
│       ├── models/        # SQLAlchemy ORM models
│       └── schemas/       # Pydantic schemas
└── 架构.md

Backend API Modules

/api/auth

– login, current user info. /api/users – user CRUD (admin). /api/rooms – study‑room management. /api/seats – seat management. /api/reservations – create/check‑in/cancel/query reservations. /api/announcements – announcement management. /api/feedbacks – feedback handling. /api/stats – statistical data. /api/upload – image upload.

Unified API prefix: /api; static resources served at /uploads mapped to D:/uploads9.

Security Mechanisms

Authentication : successful login issues a JWT (HS256) valid for 24 hours.

Authorization : HTTPBearer extracts the token; get_current_user parses it and loads the user.

Role Isolation : get_admin_user restricts admin‑only endpoints; reservation lists return only the requesting student's data.

Route Guard : front‑end router.beforeEach validates the token and redirects based on role.

Deployment & Runtime

Backend: http://127.0.0.1:8000 (API docs at /docs).

Frontend: http://localhost:5173.

Database: 127.0.0.1:3308, name db_studyroom, password 123456.

Upload directory: D:/uploads9.

Frontend proxy: in client/vite.config.js, proxy /api to the backend.

Startup Sequence : initialize the database using server/sql/init.sql → start the backend with python main.py → launch the front‑end with npm run dev.

Design Highlights

Front‑end/Back‑end separation: Vue 3 SPA + FastAPI REST API, clear responsibilities, independent development and deployment.

Dual portal design: same backend serves separate admin and student front‑ends via distinct routes and layouts.

Reservation conflict validation: server‑side check on seat + date + time‑slot prevents double booking.

Visual seat selection: student portal displays seats in a grid with real‑time status.

Data visualization: admin dashboard integrates ECharts for operational insights.

Unified response format: ResponseModel standardizes API payloads across front‑end and back‑end.