ratancloud/rklibrary

Purpose and runtime

RK Library is a full-stack, multi-user library-operations application for configuring a library, managing students and subscriptions, assigning seats by floor/shift, handling bookings and inquiries, and tracking expenses. It runs on Next.js 16 App Router/React 19 with TypeScript; server behavior is implemented through route handlers and Prisma against PostgreSQL/Neon. Primary entry points are app/layout.tsx, app/(main)/page.tsx, and app/api/auth/[...all]/route.ts.

Route shells, access, and application UI

The App Router separates authentication/onboarding from the principal application surface. Auth pages cover login, signup, and initial library setup; the main layout hosts operational modules such as dashboard, students, bookings, seats, settings, and renewals. Client components own interactive screens while their page.tsx wrappers define routes. Relevant paths: app/(auth)/layout.tsx, app/(main)/layout.tsx, app/(main)/dashboard/DashboardClient.tsx.

Authentication and tenant boundary

Better Auth provides account and session handling through a catch-all API route, with server and client integration modules. The presence of library setup and library-scoped models implies the library is the key operational ownership boundary for configuration, floors, shifts, students, and subscriptions. Route protection/routing mediation is likely centralized in proxy.ts. Paths: lib/auth.ts, lib/auth-client.ts, proxy.ts.

Core persistence model

Prisma is the persistence boundary. Its schema models User/session identities plus Library, Floor, Seat, Shift, Student, Subscription, SeatAssignment, Inquiry, and Expense operational records. Generated Prisma sources are derived artifacts; schema and migrations are the authoritative evolution path. Paths: prisma/schema.prisma, prisma/migrations/20260427171553_add_schema/migration.sql, lib/prisma.ts.

Library configuration and seat-capacity lifecycle

Administrators establish library metadata, floors, shifts, and seat maps, then maintain them through settings and library APIs. Seat-map UI renders floor/seat availability and supports assignment details; API endpoints expose floor, shift, setup, map, and seat-removal operations. This establishes capacity before student allocation. Paths: app/api/library/setup/route.ts, app/api/library/seat-map/route.ts, components/seat-map/SeatMap.tsx.

Student registration, subscriptions, and allocation

Student creation/registration captures student and document data, then subscriptions represent dated, paid/discounted access and can be renewed. Assignment is a separate booking operation linking a student to a seat and shift, protecting against double booking at the data-model/API boundary. Public registration is supported alongside staff-managed student records. Paths: app/api/student-register/route.ts, app/api/subscriptions/[id]/renew/route.ts, app/api/booking/assign-seat/route.ts.

Operational workflows and reporting

The dashboard aggregates library metrics; booking endpoints calculate availability and shifts; history surfaces prior activity. Inquiries form a lead-management funnel, while expenses are independently recorded for operations tracking. A scheduled endpoint updates subscription status, requiring an external scheduler/platform cron invocation in deployment. Paths: app/api/dashboard/route.ts, app/api/inquiry/route.ts, app/api/cron/update-subscriptions/route.ts.

Client state and external services

React Query manages server-cache interaction; Zustand holds client library/shift state. Zod and React Hook Form enforce form input handling. ImageKit is the media boundary for student/document uploads, authenticated via server routes; PDFs are generated client-side for student exports. Deployment targets Vercel, with PostgreSQL/Neon, Better Auth secrets, and ImageKit credentials supplied by environment. Paths: store/useLibraryStore.ts, app/api/imagekit/public-auth/route.ts, components/pdf/StudentPDF.tsx.