KUAS Reception

Open Campus Reception Management System — Kyoto University of Advanced Science, Faculty of Engineering

🇯🇵 日本語 README | 📋 Overview | 🚀 Setup | 📖 Docs

Cornerstone Project:
This system is being developed and operated by a 5-member student team as a Cornerstone Project of the KUAS Faculty of Engineering.
See the full project proposal here → 📄 Cornerstone Proposal (Japanese)

Overview

A modern web application that unifies open campus reception operations for visitors, reception staff, and administrators under a single UI. Currently in active development, with a demo launch at the June 2026 Open Campus and full production rollout in August 2026.

Visitors scan a pre-sent QR code for instant check-in (name/grade input available as fallback)
Reception staff manage real-time seat assignments and waitlist promotions
Administrators monitor statistics, import Excel rosters, manage programs, and control reception via an authenticated panel

Built as a React 19 + TypeScript SPA paired with Firebase Cloud Functions (Node.js 20), featuring thread-safe seat assignment via Firestore transactions.

Audience & Value

User	Value
Visitors	Zero-second QR check-in. Program, venue, and schedule info delivered by email right after registration
Reception Staff	Near-zero matching errors. Manage waitlists, manual assignments, and cancellations from one screen
Administrators	KPI dashboard, Excel roster import, and assignment mode switching via a secured admin panel
Admissions Center	Repeat visitor attendance history auto-accumulated for data-driven Open Campus improvements

Key Features

Currently Implemented

[Start] → [Name/Grade Input] → [Select Programs (up to 3)] → [Review & Submit] → [Result]

Category	Features
Visitor Reception	4-step flow · auto assignment · waitlist & promotion
Admin	KPI dashboard · manual assignment · program CRUD · open/close control
System	Firestore transactions · Firebase Auth · multilingual (JP / EN)
Infrastructure	GitHub Actions CI/CD · Firebase Hosting + Cloud Functions

In Development (Planned)

Feature	Summary
Excel Import	Upload the university-provided .xlsx roster and have it processed automatically
QR Code Email Blast	Auto-send personalized QR codes to all registered participants
QR Scan Check-in	Hold the QR up to an iPad — check-in is instant. Name/grade input as fallback
Two Assignment Modes	Type 1 (first-come) / Type 2 (batch assignment) switchable from admin settings
Post-Check-in Email	Auto-send program, venue, instructor, and schedule info immediately after check-in
Repeat Visitor Tracking	Accumulate attendance history per visitor for priority scoring and admissions analytics

See the full design and timeline in the 📄 Cornerstone Proposal (Japanese).

System Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Firebase Hosting                         │
│               React 19 SPA (Vite 7 + TypeScript)             │
│  ┌───────────────────────┐    ┌────────────────────────────┐  │
│  │   Visitor Check-in    │    │     Admin Dashboard         │  │
│  │   - QR scanner        │    │  - KPI / Stats             │  │
│  │   - Name/grade input  │    │  - Assignment board         │  │
│  │   - Program selection │    │  - Program management       │  │
│  │   - Confirmation      │    │  - Excel import             │  │
│  └──────────┬────────────┘    └────────────┬───────────────┘  │
└─────────────┼───────────────────────────────┼────────────────┘
              │ HTTP (Bearer Token)            │ Firestore onSnapshot
              ▼                                ▼
┌──────────────────────────────────────────────────────────────┐
│              Firebase Cloud Functions (Node.js 20)            │
│  ┌────────────┐  ┌─────────────┐  ┌──────────┐  ┌────────┐  │
│  │ /programs  │  │ /receptions │  │ /import  │  │  /qr   │  │
│  │ /assign... │  │ /stats      │  │ /email   │  │        │  │
│  └────────────┘  └─────────────┘  └──────────┘  └────────┘  │
│              ┌───────────────────────────┐                    │
│              │   Firestore Transaction    │                    │
│              │   (thread-safe assignment) │                    │
│              └───────────────────────────┘                    │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
           ┌──────────────────────────────┐
           │       Cloud Firestore         │
           │  programs / receptions        │
           │  assignments / settings       │
           │  participants / visitHistory  │  ← planned additions
           └──────────────────────────────┘

Directory Layout

KUAS-reception/
├── apps/
│   └── reception-web/              # React SPA
│       ├── public/                 # Static assets & logos
│       └── src/
│           ├── components/
│           │   ├── layout/         # AppShell · Sidebar · TopStatusBar
│           │   └── ui/             # Button · Card · Badge · GlassField
│           ├── features/
│           │   ├── reception/      # Full visitor reception flow
│           │   │   ├── components/ # Step-by-step components
│           │   │   ├── hooks/      # usePrograms etc.
│           │   │   └── types.ts    # Zod schema definitions
│           │   └── admin/          # Admin dashboard
│           │       ├── components/ # Panel components
│           │       └── hooks/      # useAdmin · useReservations etc.
│           ├── services/
│           │   ├── api.ts          # HTTP client (Bearer Token injection)
│           │   └── firebase.ts     # Firestore / Auth wrappers
│           └── i18n/
│               └── locales/        # ja.json / en.json / id.json
├── functions/                      # Cloud Functions
│   ├── app.js                      # Express routing
│   ├── db.js                       # Firestore transaction logic
│   ├── schemas.js                  # Zod validation schemas
│   └── middleware/auth.js          # Firebase Token verification
├── docs/
│   └── cornerstone-proposal.md    # Project proposal (Japanese)
├── firestore.rules                 # Firestore Security Rules
├── firestore.indexes.json          # Composite index definitions
└── firebase.json                   # Firebase configuration

Data Model (Firestore)

Current Collections

programs/{id}
  ├── title: string
  ├── description: string
  ├── capacity: number        # Total seat count
  ├── remaining: number       # Available seats (updated via transaction)
  ├── startTime / endTime: string
  ├── location: string
  ├── isActive: boolean
  └── order: number           # Display order

receptions/{id}
  ├── attendee
  │   ├── name / furigana / school / grade
  │   ├── companions: number  # Number of companions
  │   └── reserved: boolean   # Pre-registered flag
  ├── selections: [{id, title}]   # 1st–3rd preferences
  ├── assignedProgram: {id, title, priority, assignedBy}
  ├── status: "waiting" | "assigned" | "completed" | "cancelled"
  └── createdAt: string

assignments/{id}
  ├── receptionId / programId
  ├── attendeeName / priority
  ├── status: "confirmed" | "cancelled"
  └── assignedAt / cancelledAt: string

settings/reception-settings
  ├── isOpen: boolean
  ├── maxSelections: number
  ├── eventName / eventDate / welcomeMessage: string
  └── openTime / closeTime: string

Planned New Collections

participants/{id}                   # Created from Excel import
  ├── name / furigana / school / prefecture / grade
  ├── email: string                 # QR delivery target & visitHistory key
  ├── companions: number
  ├── selections: string[]          # CS 1st–3rd preferences
  ├── listType: "capstone" | "intro" | "both"
  ├── introTimeSlot: "am" | "pm"   # Engineering intro session slot
  ├── qrCode: string               # QR code data URL
  ├── qrSentAt: timestamp
  └── eventId: string

visitHistory/{email}               # Repeat visitor history
  ├── email / name / school: string
  ├── totalVisits: number          # Cumulative visit count
  └── visits: [{eventId, eventName, eventDate, programId, grade, checkedInAt}]

Technology Stack

Frontend

Category	Library
UI Framework	React 19, React Router 6
Data Fetching	TanStack Query 5
Forms	React Hook Form 7 + Zod
Styling	Tailwind CSS 3, Lucide Icons
i18n	i18next 24, react-i18next 15
Firebase	Firebase SDK 12 (Firestore + Auth)
Build	Vite 7, TypeScript 5

Backend

Category	Library
HTTP Server	Express 5
Firebase	firebase-admin 12, firebase-functions 6
Validation	Zod 3
Excel parsing (planned)	exceljs
Email delivery (planned)	@sendgrid/mail
QR code generation (planned)	qrcode

Infrastructure

Service	Purpose
Firebase Hosting	Static SPA hosting
Cloud Functions	API server (asia-northeast1)
Cloud Firestore	Real-time database
Firebase Authentication	Admin authentication
GitHub Actions	CI/CD (auto-deploy on main)

API Reference

Public Endpoints (no authentication required)

Method	Path	Description
`GET`	`/programs`	List all programs
`POST`	`/receptions`	Submit reception & auto-assign
`GET`	`/receptions/stats`	Fetch live statistics
`GET`	`/system/settings`	Get reception settings

Admin-Only Endpoints (Firebase ID Token required)

Method	Path	Description	Status
`PATCH`	`/programs/:id`	Update program capacity	✅ Live
`POST`	`/assignments/manual`	Manually assign a waiting guest	✅ Live
`POST`	`/assignments/:id/cancel`	Cancel assignment & auto-promote next	✅ Live
`POST`	`/import/participants`	Import Excel roster	🔜 Planned
`POST`	`/participants/:id/send-qr`	Send QR code email	🔜 Planned
`POST`	`/assignments/batch`	Run Type 2 batch assignment	🔜 Planned

Setup

Prerequisites

Node.js 20 LTS or later, npm 10 or later
Firebase CLI: npm install -g firebase-tools
A Firebase project with Firestore, Authentication, and Hosting enabled
DeepL API key (optional — for translation feature)

1. Clone and Install Dependencies

git clone <repository-url>
cd KUAS-reception
npm install
cd apps/reception-web && npm install
cd ../../functions && npm install

2. Configure Environment Variables

Create a .env file inside apps/reception-web/:

cp apps/reception-web/.env.example apps/reception-web/.env

Required (find these in Firebase Console → Project Settings → General → Your Apps):

VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_APP_ID=your-app-id

Optional:

# Cloud Functions URL (use the emulator URL during development)
VITE_API_BASE_URL=http://localhost:5001/your-project-id/asia-northeast1/api

# Set to true when using the Firebase Emulator
VITE_USE_FIREBASE_EMULATOR=true

Note: If any VITE_FIREBASE_* variable is missing, a clear error appears in the browser console and admin login will be unavailable.

3. Create an Admin Account

In the Firebase Console → Authentication → Sign-in method, enable Email/Password. Then go to the Users tab → Add user and create your admin credentials.

Development Workflow

Start the Dev Server

# From the project root
npm run dev
# → http://localhost:5173

# To reach from other devices on the same LAN
cd apps/reception-web && npm run dev -- --host

Start the Firebase Emulator

npm run emulators
# Emulator UI: http://localhost:4000

Running the emulator alongside the dev server gives you a fully local environment with no Firebase cloud calls.

Build & Deploy

# Build only
npm run build

# Deploy Hosting only
npm run deploy

# Deploy Functions only
npm run deploy:functions

# Deploy everything (Hosting + Functions)
npm run deploy:all

# Preview the built output locally
npm run preview

Quality Checks

# Static analysis (ESLint)
npm run lint

# Type checking (TypeScript)
npm run typecheck

# Unit tests
cd apps/reception-web && npm run test
cd functions && npm test

# E2E tests (Playwright)
cd apps/reception-web && npm run test:e2e

Pull Requests automatically trigger the validation workflow defined in .github/workflows/firebase-deploy.yml.

Multilingual Support

Language	File	Status
Japanese	`src/i18n/locales/ja.json`	✅ Full
English	`src/i18n/locales/en.json`	✅ Full

The browser language is detected automatically and the UI switches accordingly
Adding a new language only requires placing a new JSON file in the locales/ directory

Directory Guide

Path	Role
`apps/reception-web/src/components/layout/`	AppShell · Sidebar · TopStatusBar · FlowStepper
`apps/reception-web/src/components/ui/`	Button · Card · Badge · GlassField · EmptyState
`apps/reception-web/src/features/reception/`	Visitor-facing reception flow
`apps/reception-web/src/features/admin/`	Admin dashboard and analytics
`apps/reception-web/src/services/api.ts`	HTTP client with Bearer Token injection
`apps/reception-web/src/services/firebase.ts`	Firestore / Auth utilities
`functions/app.js`	Express routing (all API endpoints)
`functions/db.js`	Firestore transaction logic
`functions/schemas.js`	Zod validation schemas
`firestore.rules`	Firestore Security Rules
`docs/cornerstone-proposal.md`	Cornerstone project proposal (Japanese)

Release Notes

Version	Date	Highlights
v0.8.0	2026-03-27	Security fixes: removed client-injectable `status` field, added backend validation (`selections` min, `companions` max), removed mock data fallback, fixed stats double-counting bug
v0.7.0	2025-10-28	Hardened Firebase deploy workflow, refreshed documentation, configuration cleanup
v0.6.0	2025-10-09	DeepL integration improvements, stabilized deployment pipeline, enhanced language switching
v0.5.0	2025-10-02	Mobile experience updates, iPad bug fixes, Functions adjustments
v0.4.0	2025-09-30	Liquid Glass theme refinements, extended multilingual support, deployment experiments
v0.3.0	2025-09-07	Smartphone/tablet optimization, Firebase configuration updates, assorted bug fixes
v0.2.0	2025-08-23	Expanded reception flow, companion tracking, waitlist views, improved success screens
v0.1.0	2025-08-16	Initial SPA release with offline readiness and security hardening

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

KUAS Reception

Overview

Audience & Value

Key Features

Currently Implemented

In Development (Planned)

System Architecture

Directory Layout

Data Model (Firestore)

Current Collections

Planned New Collections

Technology Stack

Frontend

Backend

Infrastructure

API Reference

Public Endpoints (no authentication required)

Admin-Only Endpoints (Firebase ID Token required)

Setup

Prerequisites

1. Clone and Install Dependencies

2. Configure Environment Variables

3. Create an Admin Account

Development Workflow

Start the Dev Server

Start the Firebase Emulator

Build & Deploy

Quality Checks

Multilingual Support

Directory Guide

Release Notes

License

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

KUAS Reception

Overview

Audience & Value

Key Features

Currently Implemented

In Development (Planned)

System Architecture

Directory Layout

Data Model (Firestore)

Current Collections

Planned New Collections

Technology Stack

Frontend

Backend

Infrastructure

API Reference

Public Endpoints (no authentication required)

Admin-Only Endpoints (Firebase ID Token required)

Setup

Prerequisites

1. Clone and Install Dependencies

2. Configure Environment Variables

3. Create an Admin Account

Development Workflow

Start the Dev Server

Start the Firebase Emulator

Build & Deploy

Quality Checks

Multilingual Support

Directory Guide

Release Notes

License