Student Council Payment System (SCPS)

A complete NFC-based payment system for managing student snack bar purchases. Tap contactless cards for instant payments with real-time dashboard monitoring.

---

Features

• NFC Card Payments - Fast, cashless transactions with contactless cards
• Student Account Management - Track balances, cards, and transaction history
• Modern Web Dashboard - Built with Next.js, TypeScript, and Tailwind CSS
• CLI Tools - Quick command-line utilities for POS, top-ups, and enrollment
• Real-time Updates - Live tap notifications in the web interface
• Dual Reader Support - Run multiple NFC readers simultaneously

---

Platform

Built for Raspberry Pi 4 Model B running Raspberry Pi OS (64-bit)

Tested on:

• Raspberry Pi 4 Model B (8GB RAM recommended)
• Raspberry Pi OS (Bookworm or later)
• Debian-based Linux distributions
• Arch Linux

---

Quick Start

1. Initialize the Database

python init_db.py

2. Install Web Dependencies

cd web-next
pnpm install

3. Run the Web Interface

Development mode:

pnpm dev

Production mode:

pnpm build
pnpm start

Open http://localhost:3000 and create your admin account.

4. Next Steps

• Set up authentication - See docs/authentication.md
• Configure NFC readers - See docs/nfc-setup.md
• Deploy to production - See docs/deployment.md

---

CLI Tools

Quick operations from the command line:

• pos.py - Process payments via NFC card taps
• topup.py - Add money to student accounts
• enroll.py - Register new students and link NFC cards
• tap-broadcaster.py - Broadcast NFC taps to the web interface in real-time

Example:

python pos.py 6.5  # Charge ¥6.5 per tap

---

Documentation

Getting Started

• Getting Started - Installation and prerequisites
• Deployment Guide - Production setup with Docker, systemd, and SSL
• Security Guide - Best practices for securing your system

Configuration

• Authentication - Set up Better Auth for the web interface
• NFC Setup - Configure PN532 card readers
• Database Guide - Schema details and migrations

Usage

• User Guide - Day-to-day operations
• Scripts Reference - Utility scripts and tools

Development

• Development Guide - Architecture and extending the system
• UI Components Guide - Custom components and animations
• Testing Guide - Running tests

Support

• Troubleshooting - Common issues and solutions
• Changelog - Version history and updates

---

Supporting This Project

If you find this project helpful and would like to support its development, consider making a donation:

Bitcoin (BTC):

bc1pyv54eqxuanqgv3cm2yjl37xjxlavnh7fcfu9d3yg983uzp4qazcs5xgsz2

License

This project is licensed under the MIT License. See the LICENSE file for details.