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

1. Project Purpose and Objectives
2. Key Features
3. Technologies and Frameworks Used
4. Step-by-Step: Run the Project Locally
5. Accessing the Project Online
6. Project Structure
7. Security
8. 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

• React 19 + TypeScript
• Vite (build tool and dev server)
• Tailwind CSS v4 (via @tailwindcss/vite)
• Motion (animations)
• Lucide React (icons)
• vite-plugin-pwa (Progressive Web App support)

Ticketing / QR

• qrcode.react (QR pass generation)
• html5-qrcode (camera-based QR scanning)

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

• Node.js v20 or newer (npm included), or Bun
• Git
• A free Firebase project with Firestore enabled
• A Gemini API key (only needed for AI-powered features)

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 💪.