AC Synapse
Ananda College's digital event command center.
Real-time event updates, an interactive calendar, student ticketing with QR passes, live championship standings, and multilingual support, all in one platform.
Built for BTUI'26 - the Annual ICT day of Royal College, Colombo).
Live demo: https://ac-synapse.vercel.app
Repository: https://github.com/SinuraPerera/AC-Synapse
Table of Contents
- Project Purpose and Objectives
- Key Features
- Technologies and Frameworks Used
- Step-by-Step: Run the Project Locally
- Accessing the Project Online
- Project Structure
- Security
- About Builder
1. Project Purpose and Objectives
The problem
School events, from sports meets and cultural programs to inter-house championships, are usually coordinated through scattered notices, paper tickets, and word of mouth. Students miss updates, tickets get lost or duplicated, and nobody has a single place to follow results as they happen.
The purpose
AC Synapse gives Ananda College one digital command center for school events: a single web platform where students, staff, and organizers can follow what is happening, get into events, and track results in real time.
Objectives
- Centralize all event information in one place.
- Keep everyone informed with real-time event updates instead of static notices.
- Simplify planning with an interactive event calendar.
- Replace paper tickets with secure, scannable student QR passes and fast entry validation.
- Boost engagement with live championship standings.
- Be inclusive through multilingual support, so more of the school community can use it comfortably.
- Work anywhere: responsive on phones and installable as a Progressive Web App (PWA).
2. Key Features
| Feature | Description |
|---|
| Real-time event updates | Live announcements and event changes, synced through Firebase. |
| Interactive calendar | Browse upcoming events by date. |
| Student ticketing with QR passes | Students get a QR pass; organizers scan it with the device camera to validate entry. |
| Live championship standings | Scores and rankings update as results come in. |
| Multilingual support | The interface is available in multiple languages. |
| PWA | Installable, mobile-friendly experience. |
| Secure data layer | Firestore security rules with automated rule tests. |
3. Technologies and Frameworks Used
Frontend
Ticketing / QR
Backend / Data
- Firebase (Firestore real-time database)
- Firestore Security Rules (
firestore.rules) with tests (firestore.rules.test.ts)
- Express (server runtime support)
- Google Gen AI SDK (
@google/genai, Gemini API)
Tooling
- ESLint (with Firebase security-rules plugin),
tsx, esbuild, dotenv
- Package managers: npm (
package-lock.json) or Bun (bun.lock)
4. Step-by-Step: Run the Project Locally
Prerequisites
Step 1: Clone the repository
git clone https://github.com/SinuraPerera/AC-Synapse.git
cd AC-Synapse
Step 2: Install dependencies
npm install
(or bun install)
Step 3: Configure environment variables
Copy the example file and fill in your own values:
cp .env.example .env
Open .env and set:
GEMINI_API_KEY="your-gemini-api-key"
APP_URL="http://localhost:3000"
VITE_FIREBASE_API_KEY="your-firebase-api-key"
VITE_FIREBASE_AUTH_DOMAIN="your-project-id.firebaseapp.com"
VITE_FIREBASE_PROJECT_ID="your-project-id"
VITE_FIREBASE_STORAGE_BUCKET="your-project-id.firebasestorage.app"
VITE_FIREBASE_MESSAGING_SENDER_ID="your-sender-id"
VITE_FIREBASE_APP_ID="your-app-id"
VITE_FIREBASE_FIRESTORE_DATABASE_ID="(default)"
You can find the Firebase values in Firebase Console → Project settings → Your apps → Web app.
Step 4: Start the development server
npm run dev
Step 5: Open the app
Visit http://localhost:3000 in your browser.
Tip: to test QR scanning on a phone, open the app via your computer's local network address (the dev server is exposed on 0.0.0.0). Browsers only allow camera access on localhost or HTTPS.
Other useful commands
| Command | Purpose |
|---|
npm run build | Create an optimized production build in dist/ |
npm run preview | Preview the production build locally |
npm run lint | Type-check the project with TypeScript |
npm run clean | Remove build output |
Deploying Firestore security rules (optional)
npm install -g firebase-tools
firebase login
firebase deploy --only firestore:rules
5. Accessing the Project Online
The deployed version can be opened directly in any modern browser (desktop or mobile):
https://ac-synapse.vercel.app
No installation is required. On mobile, use "Add to Home Screen" to install it as an app.
6. Project Structure
AC-Synapse/
├── public/ # Static assets
├── src/ # Application source (React + TypeScript)
├── dev-dist/ # PWA dev output
├── .env.example # Environment variable template
├── firebase-applet-config.json
├── firebase-blueprint.json # Firestore data model blueprint
├── firestore.rules # Firestore security rules
├── firestore.rules.test.ts # Security rules tests
├── security_spec.md # Security specification
├── index.html # App entry point
├── vite.config.ts # Vite + PWA + Tailwind config
├── tsconfig.json
└── package.json
7. Security
- Firestore access is controlled by dedicated security rules (
firestore.rules) and covered by tests (firestore.rules.test.ts).
- The full security approach is documented in
security_spec.md.
- Secrets live in
.env (git-ignored). Never commit real API keys.
8. Built by M. Sinura Damsath Perera
- Developer: Sinura Perera (@SinuraPerera)
- School: Ananda College, Colombo 10
Made with effort 💪.
