{"id":51012277,"url":"https://github.com/qppd/smart-appointment-scheduling-kiosk","last_synced_at":"2026-06-21T04:31:15.789Z","repository":{"id":360692721,"uuid":"1250535434","full_name":"qppd/smart-appointment-scheduling-kiosk","owner":"qppd","description":"Web-Based Appointment Scheduling System with Automated Conflict Detection and Fingerprint Authentication Kiosk for Barangay Dolores, Taytay, Rizal","archived":false,"fork":false,"pushed_at":"2026-06-12T03:10:56.000Z","size":135,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T05:07:33.631Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qppd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T18:19:26.000Z","updated_at":"2026-06-12T03:11:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qppd/smart-appointment-scheduling-kiosk","commit_stats":null,"previous_names":["qppd/smart-appointment-scheduling-kiosk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qppd/smart-appointment-scheduling-kiosk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fsmart-appointment-scheduling-kiosk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fsmart-appointment-scheduling-kiosk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fsmart-appointment-scheduling-kiosk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fsmart-appointment-scheduling-kiosk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qppd","download_url":"https://codeload.github.com/qppd/smart-appointment-scheduling-kiosk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fsmart-appointment-scheduling-kiosk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34594326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-21T04:31:12.133Z","updated_at":"2026-06-21T04:31:15.784Z","avatar_url":"https://github.com/qppd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart Appointment Scheduling Kiosk\n\nWeb (Next.js + Firebase RTDB) → RPi4 (pyrebase4) → ESP32 (Fingerprint Sensor via Micro USB)\n\n## Architecture\n\n```\n┌─────────────┐      ┌──────────────┐      ┌─────────┐      ┌──────┐\n│  Next.js    │ ──▶ │  Firebase    │ ◀──  │  RPi4   │ ──▶ │ ESP32│\n│  (Vercel)   │      │  Auth + RTDB │      │ Headless│      │ AS608│\n│             │ ◀──  │              │ ──▶  │ Service │      │Sensor│\n└─────────────┘      └──────────────┘      └─────────┘      └──────┘\n```\n\n### Data Flow\n1. Resident books appointment via web app → writes to Firebase Realtime Database (RTDB)\n2. RPi4 polls RTDB `kiosk_commands` every 2 seconds via pyrebase4\n3. ESP32 fingerprints → RPi4 writes result back to RTDB\n4. Web app displays real-time updates via RTDB listeners\n\n## Components\n\n### 1. Web App (`src/web/`)\n- **Framework:** Next.js 14 (App Router)\n- **Auth:** Firebase Authentication (Email/Password)\n- **Database:** Firebase Realtime Database (RTDB)\n- **Styling:** Tailwind CSS\n- **Deploy:** Vercel\n\n### 2. RPi Service (`src/rpi/`)\n- **Runtime:** Python 3\n- **Firebase:** `pyrebase4` (REST API + email/password auth)\n- **Serial:** `pyserial` for ESP32 communication via micro USB (`/dev/ttyUSB0` or `/dev/ttyACM0`)\n- **Mode:** Headless daemon (no GUI)\n\n### 3. ESP32 Firmware (`src/esp/`)\n- **Library:** Adafruit Fingerprint Sensor Library\n- **Connection:** Micro USB cable to RPi4 (serial /dev/ttyUSB0)\n- **Protocol:** UART (115200 baud)\n- **Sensor:** AS608 fingerprint sensor\n- **Stability:** Watchdog-friendly with `yield()` in loops\n\n## Firebase Realtime Database (RTDB) Data Schema\n\n```\nusers/{uid}             - Resident profiles (auth-linked)\n  - first_name, last_name, email, phone, birth_date, address\n  - role: \"resident\" | \"admin\"\n  - status: \"pending\" | \"active\"\n  - fingerprint_enrolled: boolean\n  - fingerprint_template_id: number\n\nservices/{service_id}   - Available barangay services\n  - name, description, duration_minutes, slot_capacity_per_day, is_active\n\nappointments/{id}       - Booked appointments (push ID)\n  - resident_id, service_id, service_name\n  - appointment_date, start_time, end_time, queue_number\n  - status: \"scheduled\" | \"checked_in\" | \"completed\" | \"cancelled\"\n  - verified_by_fingerprint: boolean\n  - created_at: ISO string\n\nkiosk_commands/{id}     - Commands from web to RPi (push ID)\n  - type: \"verify\" | \"enroll\" | \"delete\"\n  - target_uid, slot\n  - status: \"pending\" | \"processing\" | \"completed\" | \"failed\"\n  - result: { ... }\n\nkiosk_status/{kiosk_id}  - RPi4 heartbeat \u0026 status\n  - online, last_heartbeat, esp32_connected, template_count\n```\n\n## Deployment\n\n### Web (Vercel)\n1. Create a Firebase project at https://console.firebase.google.com/\n2. Enable Authentication (Email/Password) and Realtime Database\n3. Copy `.env.example` to `.env.local` and fill in your Firebase config (including `NEXT_PUBLIC_FIREBASE_DATABASE_URL`)\n4. Deploy to Vercel\n\n### RPi4 (Headless Service)\n1. Create a kiosk user in Firebase Authentication (email/password)\n2. Create `.env` with your Firebase and auth credentials (see `.env.example`)\n3. Install Python dependencies: `pip install -r src/rpi/requirements.txt`\n4. Copy the systemd service file:\n   ```bash\n   sudo cp docs/rpi-systemd/kiosk-firebase.service /etc/systemd/system/\n   ```\n5. Enable and start:\n   ```bash\n   sudo systemctl enable --now kiosk-firebase\n   ```\n6. Check logs:\n   ```bash\n   sudo journalctl -u kiosk-firebase -f\n   ```\n\n### ESP32 (Arduino IDE)\n1. Install Adafruit Fingerprint Sensor Library (via Library Manager)\n2. Connect ESP32 to RPi4 via micro USB cable\n3. Set board to \"ESP32 Dev Module\"\n4. Upload `fingerprint_controller.ino`\n5. Verify in Serial Monitor: `OK:ESP32 ready`\n\n## Development\n\n### Web App\n```bash\ncd src/web\nnpm install\nnpm run dev          # http://localhost:3000\n```\n\n### RPi Service\n```bash\ncd src/rpi\npip install -r requirements.txt\npython main.py        # Ensure .env file is in the directory\n```\n\n## Troubleshooting\n\n- **RPi can't connect to Firebase:** Check `KIOSK_EMAIL` and `KIOS Slip to build pyrebase4; try `pip install --upgrade setuptools\n- **RPi can't connect to ESP32:** Verify serial port with `ls /dev/ttyUSB* /dev/ttyACM*`\n- **Web app Firebase errors:** Ensure `.env.local` has all required `NEXT_PUBLIC_FIREBASE_*` variables\n- **ESP32 watchdog reset:** Firmware includes `yield()` in loops; verify using stable power supply\n\n## Files Changed Summary\n\n| Path | Action | Reason |\n|------|--------|--------|\n| `src/web/backend/` | Deleted | FastAPI backend replaced by Firebase RTDB |\n| `src/web/frontend/` | Deleted | Rebuilt as Next.js app |\n| `src/web/` | New Next.js project | Firebase-first, Vercel-ready |\n| `src/rpi/ui/` | Deleted | TKinter GUI removed |\n| `src/rpi/main.py` | Rewritten | pyrebase4 polling daemon |\n| `src/rpi/services/serial_handler.py` | Updated | Auto-reconnect + ACM detection for micro USB |\n| `src/rpi/services/command_processor.py` | Created | Maps commands → ESP32 serial |\n| `src/esp/fingerprint_controller.ino` | Updated | Watchdog stability fixes |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqppd%2Fsmart-appointment-scheduling-kiosk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqppd%2Fsmart-appointment-scheduling-kiosk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqppd%2Fsmart-appointment-scheduling-kiosk/lists"}