# ratancloud/rklibrary architecture

> Architecture diagram of the GitHub repository ratancloud/rklibrary, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ratancloud/rklibrary
- Repository: https://github.com/ratancloud/rklibrary

## Overview

#### 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`.

Main entry points: [`lib/prisma.ts`](https://github.com/ratancloud/rklibrary/blob/main/lib/prisma.ts) (Prisma client), [`app/api/student-register/route.ts`](https://github.com/ratancloud/rklibrary/blob/main/app/api/student-register/route.ts) (Student registration API), [`app/(main)/layout.tsx`](https://github.com/ratancloud/rklibrary/blob/main/app/(main)/layout.tsx) (App Router shells), [`app/(main)/dashboard/DashboardClient.tsx`](https://github.com/ratancloud/rklibrary/blob/main/app/(main)/dashboard/DashboardClient.tsx) (Dashboard client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App UI"]
  node_app_shell["App Router shells<br/>Next.js routes<br/>[layout.tsx]"]
  node_dashboard_ui["Dashboard client<br/>React client UI"]
  node_client_store["Library client state<br/>Zustand store<br/>[useLibraryStore.ts]"]
  node_student_pdf["Student PDF export<br/>client PDF generator<br/>[StudentPDF.tsx]"]
end

subgraph group_auth["Identity &amp; tenancy"]
  node_auth_route["Auth API<br/>Better Auth handler<br/>[route.ts]"]
  node_auth_server["Auth server integration<br/>Better Auth<br/>[auth.ts]"]
  node_route_proxy["Route protection<br/>Next.js proxy<br/>[proxy.ts]"]
end

subgraph group_operations["Library operations"]
  node_library_setup["Library setup API<br/>route handler<br/>[route.ts]"]
  node_seat_map["Seat map UI<br/>React client UI<br/>[SeatMap.tsx]"]
  node_seat_map_api["Seat map API<br/>route handler<br/>[route.ts]"]
  node_registration["Student registration API<br/>route handler<br/>[route.ts]"]
  node_renewal["Subscription renewal API<br/>route handler<br/>[route.ts]"]
  node_seat_assignment["Seat assignment API<br/>route handler<br/>[route.ts]"]
  node_dashboard_api["Dashboard metrics API<br/>route handler<br/>[route.ts]"]
  node_inquiries["Inquiry API<br/>route handler<br/>[route.ts]"]
  node_subscription_cron["Subscription status job<br/>scheduled route handler<br/>[route.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_client["Prisma client<br/>data access<br/>[prisma.ts]"]
  node_prisma_schema["Operational schema<br/>Prisma schema<br/>[schema.prisma]"]
end

subgraph group_external["External services"]
  node_postgres[("PostgreSQL / Neon<br/>database")]
  node_imagekit_auth["ImageKit auth API<br/>route handler<br/>[route.ts]"]
  node_imagekit["ImageKit<br/>media service"]
  node_scheduler(("Deployment scheduler<br/>platform cron"))
end

node_route_proxy -->|"guards main routes"| node_app_shell
node_app_shell -->|"hosts"| node_dashboard_ui
node_dashboard_ui -->|"loads metrics"| node_dashboard_api
node_client_store -->|"provides library context"| node_seat_map
node_seat_map -->|"reads availability"| node_seat_map_api
node_auth_route -->|"uses"| node_auth_server
node_auth_server -->|"persists identities and sessions"| node_prisma_client
node_library_setup -->|"creates capacity setup"| node_prisma_client
node_seat_map_api -->|"queries seats and assignments"| node_prisma_client
node_registration -->|"creates students"| node_prisma_client
node_renewal -->|"updates subscriptions"| node_prisma_client
node_seat_assignment -->|"enforces allocation"| node_prisma_client
node_dashboard_api -->|"aggregates operations"| node_prisma_client
node_inquiries -->|"records leads"| node_prisma_client
node_subscription_cron -->|"updates statuses"| node_prisma_client
node_prisma_client -->|"implements"| node_prisma_schema
node_prisma_client -->|"reads and writes"| node_postgres
node_scheduler -.->|"invokes"| node_subscription_cron
node_imagekit_auth -->|"authorizes uploads"| node_imagekit
node_registration -->|"obtains upload authorization"| node_imagekit_auth
node_student_pdf -.->|"exports student data"| node_registration

click node_app_shell "https://github.com/ratancloud/rklibrary/blob/main/app/(main)/layout.tsx"
click node_dashboard_ui "https://github.com/ratancloud/rklibrary/blob/main/app/(main)/dashboard/DashboardClient.tsx"
click node_client_store "https://github.com/ratancloud/rklibrary/blob/main/store/useLibraryStore.ts"
click node_student_pdf "https://github.com/ratancloud/rklibrary/blob/main/components/pdf/StudentPDF.tsx"
click node_auth_route "https://github.com/ratancloud/rklibrary/blob/main/app/api/auth/%5B...all%5D/route.ts"
click node_auth_server "https://github.com/ratancloud/rklibrary/blob/main/lib/auth.ts"
click node_route_proxy "https://github.com/ratancloud/rklibrary/blob/main/proxy.ts"
click node_library_setup "https://github.com/ratancloud/rklibrary/blob/main/app/api/library/setup/route.ts"
click node_seat_map "https://github.com/ratancloud/rklibrary/blob/main/components/seat-map/SeatMap.tsx"
click node_seat_map_api "https://github.com/ratancloud/rklibrary/blob/main/app/api/library/seat-map/route.ts"
click node_registration "https://github.com/ratancloud/rklibrary/blob/main/app/api/student-register/route.ts"
click node_renewal "https://github.com/ratancloud/rklibrary/blob/main/app/api/subscriptions/%5Bid%5D/renew/route.ts"
click node_seat_assignment "https://github.com/ratancloud/rklibrary/blob/main/app/api/booking/assign-seat/route.ts"
click node_dashboard_api "https://github.com/ratancloud/rklibrary/blob/main/app/api/dashboard/route.ts"
click node_inquiries "https://github.com/ratancloud/rklibrary/blob/main/app/api/inquiry/route.ts"
click node_subscription_cron "https://github.com/ratancloud/rklibrary/blob/main/app/api/cron/update-subscriptions/route.ts"
click node_prisma_client "https://github.com/ratancloud/rklibrary/blob/main/lib/prisma.ts"
click node_prisma_schema "https://github.com/ratancloud/rklibrary/blob/main/prisma/schema.prisma"
click node_imagekit_auth "https://github.com/ratancloud/rklibrary/blob/main/app/api/imagekit/public-auth/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_dashboard_ui,node_client_store,node_student_pdf toneBlue
class node_auth_route,node_auth_server,node_route_proxy toneAmber
class node_library_setup,node_seat_map,node_seat_map_api,node_registration,node_renewal,node_seat_assignment,node_dashboard_api,node_inquiries,node_subscription_cron toneMint
class node_prisma_client,node_prisma_schema toneRose
class node_postgres,node_imagekit_auth,node_imagekit,node_scheduler toneIndigo
```

## Components

### App UI

- [App Router shells](https://github.com/ratancloud/rklibrary/blob/main/app/(main)/layout.tsx): Next.js routes · Separates auth/onboarding from the protected operational surface. · `app/(main)/layout.tsx`
- [Dashboard client](https://github.com/ratancloud/rklibrary/blob/main/app/(main)/dashboard/DashboardClient.tsx): React client UI · `app/(main)/dashboard/DashboardClient.tsx`
- [Library client state](https://github.com/ratancloud/rklibrary/blob/main/store/useLibraryStore.ts): Zustand store · Holds active library and shift state. · `store/useLibraryStore.ts`
- [Student PDF export](https://github.com/ratancloud/rklibrary/blob/main/components/pdf/StudentPDF.tsx): client PDF generator · `components/pdf/StudentPDF.tsx`

### Identity & tenancy

- [Auth API](https://github.com/ratancloud/rklibrary/blob/main/app/api/auth/%5B...all%5D/route.ts): Better Auth handler · `app/api/auth/[...all]/route.ts`
- [Auth server integration](https://github.com/ratancloud/rklibrary/blob/main/lib/auth.ts): Better Auth · `lib/auth.ts`
- [Route protection](https://github.com/ratancloud/rklibrary/blob/main/proxy.ts): Next.js proxy · Mediates protected routing. · `proxy.ts`

### Library operations

- [Library setup API](https://github.com/ratancloud/rklibrary/blob/main/app/api/library/setup/route.ts): route handler · Establishes library metadata, floors, shifts, and capacity. · `app/api/library/setup/route.ts`
- [Seat map UI](https://github.com/ratancloud/rklibrary/blob/main/components/seat-map/SeatMap.tsx): React client UI · Renders floor capacity and assignment details. · `components/seat-map/SeatMap.tsx`
- [Seat map API](https://github.com/ratancloud/rklibrary/blob/main/app/api/library/seat-map/route.ts): route handler · `app/api/library/seat-map/route.ts`
- [Student registration API](https://github.com/ratancloud/rklibrary/blob/main/app/api/student-register/route.ts): route handler · Supports public student registration and document capture. · `app/api/student-register/route.ts`
- [Subscription renewal API](https://github.com/ratancloud/rklibrary/blob/main/app/api/subscriptions/%5Bid%5D/renew/route.ts): route handler · `app/api/subscriptions/[id]/renew/route.ts`
- [Seat assignment API](https://github.com/ratancloud/rklibrary/blob/main/app/api/booking/assign-seat/route.ts): route handler · Allocates a student to a seat and shift. · `app/api/booking/assign-seat/route.ts`
- [Dashboard metrics API](https://github.com/ratancloud/rklibrary/blob/main/app/api/dashboard/route.ts): route handler · `app/api/dashboard/route.ts`
- [Inquiry API](https://github.com/ratancloud/rklibrary/blob/main/app/api/inquiry/route.ts): route handler · Manages the lead funnel. · `app/api/inquiry/route.ts`
- [Subscription status job](https://github.com/ratancloud/rklibrary/blob/main/app/api/cron/update-subscriptions/route.ts): scheduled route handler · Updates subscription status when invoked by deployment cron. · `app/api/cron/update-subscriptions/route.ts`

### Persistence

- [Prisma client](https://github.com/ratancloud/rklibrary/blob/main/lib/prisma.ts): data access · `lib/prisma.ts`
- [Operational schema](https://github.com/ratancloud/rklibrary/blob/main/prisma/schema.prisma): Prisma schema · Defines tenant-scoped library, capacity, student, subscription, booking, inquiry, and expense records. · `prisma/schema.prisma`

### External services

- **PostgreSQL / Neon**: database
- [ImageKit auth API](https://github.com/ratancloud/rklibrary/blob/main/app/api/imagekit/public-auth/route.ts): route handler · Issues server-authenticated upload access. · `app/api/imagekit/public-auth/route.ts`
- **ImageKit**: media service · Stores student and document uploads.
- **Deployment scheduler**: platform cron

## Connections

- Route protection → App Router shells: guards main routes
- App Router shells → Dashboard client: hosts
- Dashboard client → Dashboard metrics API: loads metrics
- Library client state → Seat map UI: provides library context
- Seat map UI → Seat map API: reads availability
- Auth API → Auth server integration: uses
- Auth server integration → Prisma client: persists identities and sessions
- Library setup API → Prisma client: creates capacity setup
- Seat map API → Prisma client: queries seats and assignments
- Student registration API → Prisma client: creates students
- Subscription renewal API → Prisma client: updates subscriptions
- Seat assignment API → Prisma client: enforces allocation
- Dashboard metrics API → Prisma client: aggregates operations
- Inquiry API → Prisma client: records leads
- Subscription status job → Prisma client: updates statuses
- Prisma client → Operational schema: implements
- Prisma client → PostgreSQL / Neon: reads and writes
- Deployment scheduler → Subscription status job: invokes
- ImageKit auth API → ImageKit: authorizes uploads
- Student registration API → ImageKit auth API: obtains upload authorization
- Student PDF export → Student registration API: exports student data