Beacon Chat

What it is

Beacon Chat is a real-time chat system that runs completely offline on your local network. No internet, no cloud server, no registration — you start the server on one machine and everyone else on the same LAN joins from their browser. The name says it all: the server is a beacon, clients home in on it.

All messages and profiles are persisted in SQLite, so chats survive server restarts exactly as they were.

Feature highlights

• Web frontend — neon glassmorphism theme, fully responsive (mobile + desktop)
• True real-time — messages arrive instantly over WebSocket
• Private DMs between any two people — fully private
• Group rooms — create, add/remove members, leave
• Media & files — images, video, audio and files up to 60 MB uploads
• Profiles — emoji avatar, custom color, bio
• Message edit & delete — only your own; admins can delete in groups
• Online list with live counts; typing indicator (“X is typing…”)
• Browser notifications + sound with a toggle button
• Auto-reconnect when the connection drops
• 100% local — no data ever leaves the network

Architecture & protocol

┌──────────────────────────────────────────────┐
│               LAN / WiFi                      │
│   💻 Server (web/server_ws.py)               │
│      ├─ Flask      :8080   (page + uploads)  │
│      └─ WebSocket  :8765   (real-time)       │
│   📱 💻 📱  Clients (browser) ── WebSocket ──┘
└──────────────────────────────────────────────┘

The WebSocket protocol is JSON-based:

• Client → Server: join, message, edit, delete, typing, dm-open, group-create, group-add, group-leave, profile-update
• Server → Client: welcome, rooms, message, edited, deleted, typing, users, user_joined, user_left, profile, system

SQLite schema (chat.db) — three tables:

Table	Purpose
profiles	name → avatar, color, bio (persistent)
rooms	rooms (DM/group) + member lists
messages	every message with id, room, sender, media, edit/delete state

Project structure

BeaconChat/
└── web/
    ├── server_ws.py      # unified server: Flask (HTTP+upload) + WebSocket
    ├── requirements.txt  # flask + websockets
    ├── install.sh        # one-command installer
    ├── static/           # app.js, index.html, styles.css
    ├── uploads/          # uploaded files (auto-created)
    └── chat.db           # SQLite database (auto-created)

Getting started

cd web
./install.sh
# open in a browser:
#   http://127.0.0.1:8080   (this machine)
#   http://IP-LAN:8080      (everyone else — IP is printed by the server)

Manual run: pip install -r requirements.txt && python3 server_ws.py

Why it stands out

Beacon Chat shows a product-grade understanding of real-time systems without leaning on cloud infrastructure: two transports coordinated in one 562-line server, a stable JSON protocol, complete persistence, and a polished frontend — all running on a network with no internet. It’s the kind of tool that just works at a family gathering or in an office with restricted internet.