B

Beacon

Centralized communication, decentralized outreach. A powerful Telegram integration for College Student Committees.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. Contact

About The Project

Beacon bridges the gap between the College Student Committee (CSC) and individual House Chats. By leveraging Telegram's native APIs and a powerful Next.js dashboard, Beacon streamlines outreach, announcements, and feedback collection while maintaining a standardized message flow.

Value Proposition:

• Centralized Communication, Decentralized Outreach: Allows the CSC to broadcast messages from a single interface while reaching students directly in their decentralized House Chats.
• Smart Organization & Filtering: Tag broadcasts with custom, dynamic categories (like Events, Elections, Admin) to keep your communication history clean and easily searchable.
• Live Telegram Sync: Made a typo? Edit text announcements directly from the dashboard and watch them update live across all Telegram group chats.
• Standardized Message Flow: Ensures that announcements, infographics, and polls are delivered consistently and professionally across all channels.

(back to top)

Built With

• 
• 
• 
• 

(back to top)

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

You need Node.js installed, as well as a Supabase project and a Telegram Bot Token.

• npm

  npm install npm@latest -g

Installation

1. Get a free API Key at https://supabase.com
2. Get a free Telegram Bot Token from @BotFather on Telegram
3. Clone the repo

   git clone https://github.com/chaipinzheng/beacon.git

4. Run the onboarder setup script from the project root

   npm run setup

5. Set up your Database Schema in Supabase using the provided .sql file in web/supabase/schema.sql.
6. Fill in the generated web/.env.local

   NEXT_PUBLIC_SUPABASE_URL="ENTER YOUR SUPABASE URL"
   SUPABASE_SERVICE_ROLE_KEY="ENTER YOUR SUPABASE SERVICE ROLE KEY"
   TELEGRAM_BOT_TOKEN="ENTER YOUR TELEGRAM BOT TOKEN"
   NEXT_PUBLIC_BEACON_PUBLIC_DEMO="false"

7. Run the development server

   npm run dev

Public Playground

If you deploy the web app publicly, visitors can use the /try page to test Beacon online with their own Telegram bot token and chat IDs.

• Tokens submitted on /try are used only for that request and are not written to Supabase.
• The playground supports one-off announcements, photo announcements, and polls.
• The main dashboard remains the full self-hosted Beacon experience backed by your own Supabase project and Telegram webhook.

Public Demo Mode

To turn Beacon into a polished read-only public demo, set this environment variable on the web app:

NEXT_PUBLIC_BEACON_PUBLIC_DEMO="true"

• The dashboard becomes a curated read-only view.
• Compose, category management, and inline editing are hidden and blocked with 403 responses.
• The /try playground remains available for live testing with each visitor's own Telegram bot token.

To reset the shared demo dataset, run the SQL in web/supabase/demo-seed.sql in your Supabase SQL editor.

(back to top)

Usage

Beacon comes with powerful core pages tailored for the CSC workflow:

1. The Dashboard & Live Editing Monitor active houses, reach statistics, and recent broadcasts centrally. Filter your history by custom categories, or quickly edit past announcements to sync corrections to Telegram.

2. The Compose Interface Draft rich-text announcements or interactive "Interest-Check" Polls with dynamic options. Tag them with categories before sending to keep your feed organized.

3. Category Management Create and manage your own custom tracking tags (with colors) to easily distinguish between Elections, Events, and Admin alerts.

For more examples, please refer to the Documentation

(back to top)

Roadmap

• Integrate standard text announcements
• Add multi-option polling support
• Provide unified analytics view
• Dynamic broadcast categorization & filtering
• Inline Telegram message editing from dashboard
• Add role-based access control (RBAC)
• Implement advanced message scheduling

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Contact

Project Link: https://github.com/chaipinzheng/beacon

(back to top)