Hostel

One-line: Run a school’s boarding facilities end-to-end — buildings, rooms and beds, student allocations, visitor logging, and a night/day-out gate-pass workflow with warden and gatekeeper roles.

What it does

Hostel gives a boarding school a single place to manage where residents sleep and who comes and goes.

Facilities structure — a Hostel (building) contains HostelRooms (each with a floor and capacity), and each room contains individual HostelBeds.
Allocation — assign a student to a specific bed; the system tracks the active assignment plus full history.
Residents — see who lives in each bed, with a one-page warden view per student (allocation, history, fee status, recent gate-passes and visitors).
Visitors — check guests in and out against a repeat-visitor profile, with a live “currently inside” panel.
Gate-pass workflow — students request a night/day-out; a warden approves or rejects (after calling the parent), and a gatekeeper marks the actual departure and return. Overdue returns are flagged automatically.

Who uses it

Hostel admin / warden — authors buildings, rooms and beds; allocates students; approves or rejects gate-passes; monitors occupancy and overdue alerts.
Gatekeeper — marks checkout (departure) and checkin (return) at the gate; logs visitors in and out.

A mobile hostel-admin module mirrors the core flows: dashboard, buildings then rooms then a bed grid, gate-pass handling, residents, and visitors.

Key concepts

Building (Hostel) — a physical hostel facility, tenant-scoped and soft-deletable.
Room (HostelRoom) — a room on a floor, with a capacity.
Bed (HostelBed) — a single bed; carries denormalized allocation fields for fast grid rendering.
Allocation (HostelAllocation) — a student-to-bed assignment; one active allocation per bed is enforced at the database level.
Resident — a student with an active allocation.
Visitor log (HostelVisitorLog) — a check-in/check-out event tied to a repeat HostelVisitor profile.
Gate pass (HostelGatepass) — a student out-request driven by a state machine: pending to approved to active to closed, with rejected and overdue branches.

How it works

Structural authoring happens on the web: add a hostel, add rooms (floor + capacity), add beds (auto-numbered), then allocate students by clicking a vacant bed and picking a student and check-in date. Checking out an allocation frees the bed.

The gate-pass flow is permission-gated by role. A warden runs approve / reject; a gatekeeper runs checkout / checkin at the gate. Every transition is written to an append-only audit trail. Visitors are handled separately: check-in upserts a visitor profile and opens a log; check-out closes it.

Rules & edge cases

Gated by the plan/feature key hostel — when a tenant has it disabled, the nav link, all /api/hostel/* routes, and the admin-web module become inaccessible.
Everything is tenant-scoped and gate-pass and allocation actions are permission-gated (separate warden, gatekeeper, and manage permissions).
List responses are enriched with student_name and admission_number (and visitor name/phone on visitor logs) so views show human labels, not raw UUIDs.
Deleting an allocated bed is refused.
Status: Per the source module doc, Hostel is built server-side (models, services, 32 routes, RBAC, Celery overdue/rollover jobs, 136 passing tests) and has full admin-web screens plus the mobile hostel-admin module. Earlier roadmap notes had flagged hostel as plan-key/partial; the current module documentation describes it as complete, so treat it as built server-side and on mobile admin. Deferred items remain out of scope: biometric/RFID access, mess and laundry, room-change requests, and SMS delivery of parent notifications.

Where it lives

Backend: server/modules/hostel/ (plus server/tasks/hostel.py for Celery jobs)
Admin web: admin-web/src/app/(dashboard)/hostel/
Mobile: hostel-admin module in the mobile client
Plan/feature key: hostel

Transport Notifications & Announcements