Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/muhammadbugaje/gobarau_backend/llms.txt

Use this file to discover all available pages before exploring further.

The Services module extends Gobarau Academy’s backend with two core student support systems: the school library and the student transport network. The library sub-domain manages the full book lifecycle — cataloguing titles, tracking who has borrowed what and when, and recording overdue fines for unreturned books. The transport sub-domain handles route definitions, the vehicle fleet, and per-student subscription enrollments that map a student to a specific bus route and direction for an academic session. All endpoints require authentication and IsStaffOrAdmin permissions.

​
Library

​
Books

The Book model represents the library’s physical inventory. Each title carries availability counters so staff can instantly see how many copies are on the shelf versus checked out.

​
GET /api/services/books/

Returns the full catalogue of library books ordered alphabetically by title. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the book record.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
title
string
Full title of the book (max 200 characters).
​
author
string
Author name(s). Optional — defaults to "".
​
isbn
string
ISBN number (max 20 characters). Must be unique across the catalogue. Optional — defaults to "".
​
genre
string
Genre or subject classification (max 100 characters). Optional — defaults to "".
​
quantity_total
integer
Total number of copies owned by the library. Defaults to 1.
​
quantity_available
integer
Number of copies currently available for borrowing. Defaults to 1.
​
location
string
Shelf or section location within the library (max 100 characters). Optional — defaults to "".
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/services/books/

Adds a new book to the library catalogue. Permissions: IsAuthenticated, IsStaffOrAdmin
​
title
string
required
Full title of the book. Maximum 200 characters.
​
author
string
Author name(s). Optional.
​
isbn
string
Unique ISBN. Optional but must be unique if provided.
​
genre
string
Genre or subject area. Optional.
​
quantity_total
integer
Total copies acquired. Defaults to 1.
​
quantity_available
integer
Copies currently available. Defaults to 1. Should not exceed quantity_total.
​
location
string
Shelf/section location (e.g., "Shelf B-3"). Optional.

​
Borrow Records

A BorrowRecord is created each time a patron checks out a book. It tracks the expected return date and the actual return date, and its status moves through borrowed → returned (or overdue if the due date passes without a return).
The borrow_date field is set automatically to today’s date on creation (auto_now_add=True) and cannot be supplied in the request body.

​
GET /api/services/borrow-records/

Returns all borrow records ordered by most recent borrow date first. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the borrow record.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
book
integer (FK)
ID of the Book that was borrowed.
​
borrower
integer (FK)
ID of the Person (from accounts.Person) who borrowed the book.
​
borrow_date
string (date)
Date the book was checked out. Set automatically on creation.
​
due_date
string (date)
Expected return date in YYYY-MM-DD format.
​
return_date
string (date) | null
Actual return date. null while the book is still out.
​
status
string (enum)
Current status of the borrow. One of: borrowed, returned, overdue.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.
​
created_by
integer (FK) | null
ID of the staff member who created this record (from AuditMixin).
​
updated_by
integer (FK) | null
ID of the staff member who last modified this record.

​
POST /api/services/borrow-records/

Creates a new borrow record, i.e., checks a book out to a borrower. Permissions: IsAuthenticated, IsStaffOrAdmin
​
book
integer
required
ID of the Book being borrowed.
​
borrower
integer
required
ID of the Person checking out the book.
​
due_date
string (date)
required
Expected return date in YYYY-MM-DD format.
​
return_date
string (date)
Actual return date. Supply when recording a return. Defaults to null.
​
status
string (enum)
Borrow status. Defaults to borrowed. Options: borrowed, returned, overdue.
# Check out a book to a borrower
curl -X POST https://api.gobarauacademy.edu.ng/api/services/borrow-records/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "book": 15,
    "borrower": 88,
    "due_date": "2025-02-14",
    "status": "borrowed"
  }'

​
Library Fines

Library fines are levied against overdue borrow records. They are tracked independently of the main Finance payments module — a fine here captures the overdue debt, while settlement through the Finance module is handled separately.
Library fines are not automatically linked to a Payment record in the Finance module. They represent the outstanding debt only. Staff must reconcile fine payments separately through the finance workflow if required.

​
GET /api/services/library-fines/

Returns all library fine records ordered by most recently created. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the fine record.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
borrow_record
integer (FK)
ID of the BorrowRecord this fine was levied against.
​
amount
string (decimal)
Fine amount (up to 10 digits, 2 decimal places), e.g., "200.00".
​
paid
boolean
Whether the fine has been paid. Defaults to false.
​
paid_at
string (ISO 8601 datetime) | null
Timestamp of when the fine was cleared. null until paid.
​
created_at
string (ISO 8601 datetime)
Timestamp when the fine was raised.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/services/library-fines/

Creates a new fine record against an overdue borrow record. Permissions: IsAuthenticated, IsStaffOrAdmin
​
borrow_record
integer
required
ID of the BorrowRecord triggering the fine.
​
amount
string (decimal)
required
Fine amount, e.g., "150.00".
​
paid
boolean
Set to true to immediately mark as settled. Defaults to false.
​
paid_at
string (ISO 8601 datetime)
Timestamp of payment. Required if paid is true. Defaults to null.

​
Transport

​
Bus Routes

A BusRoute defines a named corridor between an origin and destination, with optional intermediate stops stored as a JSON array. Multiple vehicles can be assigned to a single route.

​
GET /api/services/bus-routes/

Returns all defined bus routes ordered alphabetically by name. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the route.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
name
string
Route name (max 200 characters), e.g., "Northern Zone Route".
​
origin
string
Starting point of the route (max 200 characters).
​
destination
string
End point of the route (max 200 characters).
​
stops
array
JSON array of intermediate stop names. Defaults to [].
​
distance_km
string (decimal)
Total route distance in kilometres (up to 5 digits, 2 decimal places). Defaults to "0.00".
​
created_at
string (ISO 8601 datetime)
Timestamp when the route was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/services/bus-routes/

Creates a new bus route. Permissions: IsAuthenticated, IsStaffOrAdmin
​
name
string
required
Display name for the route. Maximum 200 characters.
​
origin
string
required
Starting location of the route.
​
destination
string
required
End location of the route.
​
stops
array
Optional JSON array of intermediate stop strings, e.g., ["Kofar Wambai", "Rijiyar Zaki"]. Defaults to [].
​
distance_km
string (decimal)
Route distance in km. Defaults to "0.00".

​
Bus Vehicles

Each BusVehicle record tracks a physical school bus identified by its unique registration number. A vehicle is optionally assigned a driver and a route.
Both driver and route use SET_NULL on delete — removing a driver or route will not delete the vehicle record; those fields will simply become null.

​
GET /api/services/bus-vehicles/

Returns all registered vehicles ordered by registration number. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the vehicle record.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
registration_number
string
Official vehicle registration plate (max 20 characters). Must be unique.
​
capacity
integer
Maximum passenger capacity. Defaults to 30.
​
driver
integer (FK) | null
ID of the Person (accounts) assigned as driver. Nullable.
​
route
integer (FK) | null
ID of the BusRoute this vehicle currently serves. Nullable.
​
created_at
string (ISO 8601 datetime)
Timestamp when the vehicle was registered.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/services/bus-vehicles/

Registers a new school bus vehicle. Permissions: IsAuthenticated, IsStaffOrAdmin
​
registration_number
string
required
Vehicle registration plate. Must be unique. Maximum 20 characters.
​
capacity
integer
Passenger capacity. Defaults to 30.
​
driver
integer
Optional ID of the assigned driver (Person). Can be null.
​
route
integer
Optional ID of the assigned BusRoute. Can be null.

​
Transport Subscriptions

A TransportSubscription enrolls a student on a specific bus route for an academic session, capturing the travel direction and the subscription fee charged.
The combination of student, session, and route must be unique. A student cannot be subscribed to the same route twice in the same session. Attempting a duplicate subscription will return 400 Bad Request.

​
GET /api/services/transport-subscriptions/

Returns all transport subscriptions ordered by most recently created. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the subscription.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
student
integer (FK)
ID of the subscribed StudentProfile.
​
route
integer (FK)
ID of the BusRoute the student is enrolled on.
​
session
integer (FK)
ID of the AcademicSession this subscription covers.
​
direction
string (enum)
Travel direction. One of: to_school, from_school, both. Defaults to both.
​
fee_amount
string (decimal)
Transport fee charged for this subscription.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.
​
created_by
integer (FK) | null
ID of the staff member who created this record (from AuditMixin).
​
updated_by
integer (FK) | null
ID of the staff member who last updated this record.

​
POST /api/services/transport-subscriptions/

Enrolls a student on a bus route for the given session. Permissions: IsAuthenticated, IsStaffOrAdmin
​
student
integer
required
ID of the StudentProfile to enroll.
​
route
integer
required
ID of the BusRoute to subscribe to.
​
session
integer
required
ID of the AcademicSession this subscription covers.
​
fee_amount
string (decimal)
required
Transport fee for the subscription, e.g., "30000.00".
​
direction
string (enum)
Direction of travel. Defaults to both. Options: to_school, from_school, both.
# Subscribe a student to a bus route for the current session
curl -X POST https://api.gobarauacademy.edu.ng/api/services/transport-subscriptions/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 42,
    "route": 3,
    "session": 5,
    "direction": "both",
    "fee_amount": "30000.00"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us