A complete library management system for Holy Redeemer School of Cabuyao, featuring RFID-based circulation, QR code tracking, fine management, and comprehensive reporting.
- Role-Based Access Control - Admin, Librarian, and Student portals with appropriate permissions
- Book Management - Full CRUD operations with multiple copy tracking
- Catalog Search - Full-text search by title, author, ISBN, and category
- QR Code System - Automatic QR generation for every book copy (format:
HR-{id[:8]}-C{n}) - Circulation - RFID/QR-based checkout, return, and renewal
- Fine Management - Automatic fine calculation, partial payments, and tracking
- Analytics and Reports - Interactive charts, usage statistics, and exportable reports
- Security - JWT authentication, audit logging, password hashing
- Responsive Design - Mobile-friendly interface for students
- Student Achievements - Gamification system with badges and reading goals
- Favorites - Students can bookmark books for later
Run everything with a single command:
# First time setup
./setup_and_run.sh --setup
# After setup, run the application
./setup_and_run.sh --run
# Reset database with seed data
./setup_and_run.sh --seedThis script:
- Sets up environment variables
- Starts PostgreSQL database via Docker
- Installs Go tools (air, goose, sqlc)
- Runs database migrations and seeds
- Installs frontend dependencies
- Starts both backend and frontend servers
cd backend
# Create environment file
cp .env.example .env
# Edit .env with your database URL
# Install Go tools
go install github.com/air-verse/air@latest
go install github.com/pressly/goose/v3/cmd/goose@latest
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
# Run migrations
goose -dir internal/database/migrations postgres "$DATABASE_URL" up
# Start dev server (with hot reload)
make devBackend runs on: http://localhost:8080
cd frontend
# Create environment file
cp .env.example .env
# Install dependencies
npm install
# Start dev server
npm run devFrontend runs on: http://localhost:4127
| Role | Username | Password | Access |
|---|---|---|---|
| Super Admin | admin |
admin123 |
Full system access |
| Librarian | librarian |
lib123 |
Circulation, books, reports |
| Student | student001 |
student123 |
Catalog, account, requests |
HolyRedeemer/
├── backend/ # Go 1.24 + Gin REST API
│ ├── cmd/server/ # Application entry point
│ ├── internal/
│ │ ├── config/ # Configuration management
│ │ ├── database/ # DB connection & migrations
│ │ │ ├── migrations/ # SQL migration files
│ │ │ └── queries/ # sqlc query definitions
│ │ ├── handlers/ # HTTP request handlers
│ │ ├── middleware/ # Auth, CORS, logging
│ │ ├── repositories/ # Generated sqlc code
│ │ ├── cache/ # In-memory caching
│ │ └── utils/ # JWT, password, QR utilities
│ ├── pkg/response/ # Standardized API responses
│ ├── Makefile # Build commands
│ └── README.md # Backend-specific docs
│
├── frontend/ # React 18.3 + TypeScript + Vite
│ ├── src/
│ │ ├── components/ # React components (shadcn/ui)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── pages/ # Page components by role
│ │ │ ├── admin/ # Admin pages
│ │ │ ├── librarian/# Librarian pages
│ │ │ └── student/ # Student pages
│ │ ├── services/ # API service layer
│ │ └── stores/ # Zustand state stores
│ ├── package.json
│ └── README.md # Frontend-specific docs
│
├── docs/ # Project documentation
│ ├── api/ # API reference
│ ├── architecture/ # System architecture
│ └── guides/ # Development guides
│
├── .github/workflows/ # CI/CD pipelines
├── setup_and_run.sh # Quick setup script
├── docker-compose.yml # Database container
├── DATABASE_SCHEMA.md # Database schema documentation
└── README.md # This file
| Document | Description |
|---|---|
| API Reference | Complete REST API documentation |
| Architecture | System design, code patterns, database schema |
| Contributing | Development setup and guidelines |
| Database Schema | Complete database schema with Mermaid diagrams |
- Language: Go 1.24+
- Framework: Gin 1.11
- Database: PostgreSQL 15 (Neon serverless)
- Tools:
- sqlc - Type-safe SQL code generation
- goose - Database migrations
- Bcrypt - Password hashing
- JWT - Authentication
- In-memory cache - Performance optimization
- Framework: React 18.3.1
- Language: TypeScript 5.8.3
- Build Tool: Vite 5.4.19
- Styling: TailwindCSS 3.4.17
- UI Components: Shadcn/UI (Radix UI)
- State Management:
- TanStack Query 5.83 - Server state and caching
- Zustand 5.0.9 - Client state
- Specialized Libraries:
- html5-qrcode - QR/barcode scanning
- qrcode.react - QR generation
- Recharts - Charts for reports
- date-fns - Date manipulation
- xlsx - Excel import/export
- React Router DOM - Client routing
- React Hook Form - Form management
- Zod - Schema validation
- Framer Motion - Animations
- Database: PostgreSQL 15 (Docker for local dev, Neon for production)
- Authentication: JWT (15min access, 7 day refresh)
- API: RESTful API with Gin framework
- Ports: Frontend 4127, Backend 8080, PostgreSQL 5433
- Dashboard - System-wide statistics and overview
- User Management - Create, edit, and archive users (students, librarians, admins)
- Book Management - Full CRUD for books and categories with Excel import/export
- QR Management - Generate and print QR codes for book copies
- Settings - Configure library policies (fine rates, loan periods, limits)
- Audit Logs - Track all system actions for security
- Reports - Visual analytics and downloadable reports
- Cache Management - Clear server cache when needed
- Dashboard - Daily operations overview
- Circulation - RFID/QR-based checkout and return station
- Student Lookup - Find students, view their loans, fines, and history
- Book Catalog - Search and manage book inventory
- Daily Operations - Review due items, overdue books, and pending requests
- Reports - Operational reports and statistics
- Catalog - Search and browse library inventory
- Dashboard - Personal overview of active loans and fines
- Account - View borrowing history, active requests, and fine details
- Notifications - In-app alerts for due dates and request updates
- Book Requests - Reserve or request unavailable books
- Favorites - Bookmark books for quick access
- Achievements - Earn badges for reading milestones
cd backend
make dev # Start with hot reload (air)
make run # Build and run
make test # Run tests
make lint # Run linter (golangci-lint)
make sqlc # Regenerate sqlc code
make migrate-up # Apply database migrations
make migrate-down # Rollback migration
make reset-db # Drop schema + re-migrate
make build # Build binary
make clean # Remove build artifactscd frontend
npm run dev # Start dev server
npm run build # Production build
npm run preview # Preview production build
npm run test # Run Vitest tests
npm run test:e2e # Run Playwright E2E tests
npm run lint # Run ESLint| Table | Description |
|---|---|
| users | Authentication and user accounts |
| students | Student profiles with RFID codes |
| librarians | Staff accounts |
| books | Book catalog |
| book_copies | Individual physical copies with QR codes |
| transactions | Circulation records (checkout/return) |
| fines | Fine records |
| payments | Fine payment history |
| book_requests | Reservation system |
| notifications | In-app user notifications |
| audit_logs | Security audit trail |
| library_settings | System configuration |
| categories | Book categorization |
| refresh_tokens | JWT refresh token management |
| favorite_books | Student bookmarked books |
| achievements | Gamification badges |
| student_achievements | Student earned badges |
See DATABASE_SCHEMA.md for complete schema details with Mermaid diagrams.
- Authentication: JWT tokens with automatic refresh
- Password Hashing: Bcrypt (cost: 10)
- Role-Based Access: Middleware enforces role permissions
- Audit Logging: All sensitive actions logged
- CORS Protection: Configurable allowed origins
- Input Validation: Request validation on all endpoints
- SQL Injection Protection: Parameterized queries via sqlc
cd backend
make testCurrent coverage: ~87% for handlers
cd frontend
npm run testCurrent status: 89/92 tests passing (3 known jsdom issues)
cd frontend
npm run test:e2e- Frontend Login Tests - 3 tests fail in Vitest due to jsdom not providing
ResizeObserverAPI. This is a test environment issue only; the feature works correctly in browsers.
MIT License
Please see Contributing Guide for development setup and guidelines.
Holy Redeemer School of Cabuyao - Library Management System Development Team