Django Backend Development & Design Documentation

Author: Zhenyu Yang yangzhenyu@sust.edu.cn, Sixu Wei reisa@sust.edu.cn

Last updated: Apr 24, 2026

This document serves as the unified entry point for the backend/ Django server implementation, consolidating system-level design, reading navigation, and app documentation indexes that were previously spread across backend.md and design.md.

Document Scope

• This page answers “how is the system layered, how do business flows work, and where should I start reading the code.”

• dev/backend/*.md sub-pages answer “how is each app currently implemented.”

• api/*.md answers “how to call the APIs.”

Reading Order

1. Start with Architecture Overview to build a holistic understanding of configuration, routing, authentication, and cross-app dependencies.

2. Then read the system-level roles, flows, and module collaboration on this page.

3. Proceed to the app-specific documentation for each business module.

4. Finally, consult the corresponding API documentation for request/response details.

Core Roles

Admin-Side Roles

Role	Identifier	Primary Responsibilities
Super Admin	superadmin	Global configuration, account roles, classroom management, final approval, signage management
Academic Secretary	secretary	First review of teaching activities, course import, classroom info maintenance, user status maintenance
Office Assistant	assistant	Second review of reservations, repair ticket handling, check-in management, course/reservation rescheduling
Counselor	counselor	First review of student activities, partial repair ticket viewing and handling

User-Side Roles

Role	Identifier	Primary Responsibilities
Chinese Teacher	chinese_teacher	Apply for reservations, view courses, create check-in sessions
Foreign Teacher	foreign_teacher	Register account, apply for reservations, view courses, create check-in sessions
Student	student	View personal course check-ins, submit reservation applications, report repairs, report violations

Module Collaboration

accounts
  ├─ Provides users, roles, login, two-factor authentication
  ├─ Provides authentication for all business endpoints
  └─ Provides current_role as a runtime context

courses
  ├─ Generates CourseOccurrence as the factual class record
  ├─ Provides time-slot basis for classrooms/signage/borrowings/checkins
  └─ Depends on common.SystemConfig for seasonal schedules

classrooms
  ├─ Maintains classroom master data
  └─ Aggregates courses and reservations into classroom schedules

borrowings
  ├─ Depends on classrooms as the resource object
  ├─ Depends on courses for conflict validation
  └─ Depends on accounts.current_role for approval routing

checkins
  └─ Depends on CourseOccurrence to create check-in sessions

signage
  ├─ Binds one-to-one with classrooms via devices
  └─ Depends on courses to render display schedules

Key Flows

Reservation Approval

1. A user submits a reservation application based on their role and activity type.

2. The system validates the time window, capacity, and conflicts first.

3. First review is routed to counselor or secretary based on activity type.

4. After first review approval, the request moves to second review by assistant.

5. The reservation takes effect after second review approval; superadmin can directly grant final approval.

Courses & Classroom Occupancy

1. An admin imports the course schedule; the system generates Course and CourseOccurrence records.

2. Classroom schedules and free classroom queries are both derived from CourseOccurrence overlaid with manual reservations.

3. Signage display also reads course instances directly, rather than maintaining a separate schedule.

Check-ins

1. A teacher or check-in admin creates a CheckinSession based on a CourseOccurrence.

2. The system automatically transitions session status based on the class period and current time.

3. Teachers manually maintain CheckinRecord entries through the roster.

Signage Activation

1. An admin issues a one-time activation code for a classroom.

2. The device scans the code and calls the activation endpoint to exchange it for a long-lived device token.

3. The device subsequently uses only the device token to fetch classroom info and course schedules.

Documentation Index

• Backend Architecture Overview
• accounts Accounts & Authentication
• classrooms Classroom Management
• signage Signage Devices
• courses Courses & Seasonal Schedules
• checkins Class Check-ins
• borrowings Classroom Reservations & Approval
• repairs Repair Tickets
• abuse Violation Reports
• logs Operation Logs
• common & Shared Services

Module Map

Module	Code Entry	Description	API Docs
accounts	backend/apps/accounts/	Accounts, login, roles, TOTP, WebAuthn, WeChat binding	accounts.md
classrooms	backend/apps/classrooms/	Classroom master data, free classrooms, classroom schedule, classroom import	classrooms.md
signage	backend/apps/signage/	Signage device activation, device authentication, signage config, signage schedule	signage.md
courses	backend/apps/courses/	Course master records, class occurrences, import/export, rescheduling, seasonal schedules	courses.md
checkins	backend/apps/checkins/	Check-in sessions, check-in records, roster, manual check-in	checkins.md
borrowings	backend/apps/borrowings/	Classroom reservation applications, two-level approval, course-reservation rescheduling	borrowings.md
repairs	backend/apps/repairs/	Repair tickets, emergency repairs, status transitions	repairs.md
abuse	backend/apps/abuse/	Violation report submission and handling	abuse.md
logs	backend/apps/logs/	Operation log queries and export	logs.md
common / services	backend/common/, backend/services/	System config, uploads, pagination, middleware, shared services	common.md

Maintenance Principles

• Code is the source of truth; historical requirement tables are not reproduced here.

• Business rules should live on their respective app pages; cross-module constraints belong in Architecture Overview.

• Request parameters, response examples, and error codes are documented in the API docs; this page only covers implementation and maintenance highlights.