Spark

1. Tech Stack

Layer	Technology	Notes
Backend	Node.js + Express 4	REST API + static file serving
Real-time	Supabase Realtime	Instant messaging via DB subscriptions
Database	Supabase (PostgreSQL)	Cloud Postgres + Realtime + Storage
Auth	JWT + bcryptjs	7-day tokens stored in localStorage
File Uploads	Multer	Profile photos (5 MB), chat files (10 MB)
Frontend	HTML + CSS + Vanilla JS	No framework - zero build step

2. How to Run

Prerequisites

Node.js v16 or later (nodejs.org)
A terminal / command prompt

First-time setup

Open a terminal in the project folder and run:

cd "C:\Users\andre\Documents\Deepseek\Code App" npm install

Start the server

node server.js

Open in browser

Navigate to http://localhost:3000
Register an account, complete your profile, then start browsing.
Admin panel: http://localhost:3000/admin.html

⚠ Always use http://localhost:3000 - opening the HTML file directly via file:// will not work.

3. Features

3.1 Authentication

public/index.html · server.js

Register with username, email, and password (bcrypt-hashed - never stored plain)
Login returns a 7-day JWT stored in localStorage
Forgot password - 2-step: verify email, then set a new password (no email server needed)
Change password on the Profile page (current password required)
Clear error shown when app is opened as file:// instead of http://localhost:3000
Google OAuth login - sign in with Google via Supabase, auto-creates account if new user
Facebook OAuth login - sign in with Facebook via Supabase, auto-creates account if new user
OAuth users get profile info (name, email, avatar) pre-filled from provider

3.2 Profile

public/profile.html · server.js

Upload a profile photo (JPEG / PNG, max 5 MB) shown as a circular thumbnail
Set display name, age, gender, and bio (300-character counter)
Email shown read-only
Navbar chip shows name and avatar on all pages; falls back to initial letter

3.3 Discover / Browse

public/browse.html · server.js · public/nav.js · public/style.css

Responsive card grid of all members who completed their profile
88 px circular photo with a green/grey online status dot — updates every 30s without page reload
Shows name, age, gender, bio, and human-readable status (Active now, Recently active, etc.)
Search bar: Searches name, username, bio, gender, and interests as you type
Filter pills: All, 🟢 Active Now (online + recently active), ⭐ Recently Joined
Active Now section at top shows currently online members, with "View all" shortcut
Deterministic vibe tags based on user ID — same user always shows same tags; search matches them
Click any card or Message button to open a chat with that person
Your own card is included and always shows Online while you are logged in

3.4 Real-Time Chat

public/chat.html · server.js

Instant messaging via Supabase Realtime - no page refresh needed
Conversation sidebar with last-message preview and per-conversation unread badge
Emoji picker with 7 categories: Smileys, Hearts, Hands, Nature, Food, Activity, Symbols
File & image sharing up to 10 MB; images shown inline, other files as download links
Preview bar before sending with X to cancel
Edit own messages - hover to reveal button, confirm with Enter; shows "(edited)"
Delete own messages - removed instantly for both sender and receiver

3.5 Online / Offline Presence

public/global.js · public/nav.js · server.js · browse.html · chat.html

🟢 Green = online / recently active, ⚫ Grey = offline on every member card, drawer, and chat header
Sidebar drawer shows "Online now" with green dot when user is active — no more "Offline · just now"
Heartbeat system: nav.js ping every 30s (3min when tab hidden), global.js ping every 45s + activity-triggered
Activity detection: scrolling, clicking, typing, or touching triggers immediate heartbeat
Visibility API: fast heartbeat when tab visible, slow when backgrounded
Browse & chat pages poll member status every 30s — dots update without page refresh
Tab close / logout: beforeunload sends offline signal via fetch+keepalive (not broken sendBeacon)
/api/logout sets lastSeen to 6 min ago so the 5-min online window correctly marks offline
Online window: API marks user as online if lastSeen is within last 5 minutes or heartbeat is active
Status labels: "Online now", "Active Xm ago", "Offline" — human-readable, no awkward combinations

3.6 Unread Badges & Browser Notifications

public/chat.html · public/global.js

Red badge counter per conversation in the sidebar
Nav-bar badge showing total unread count across all conversations
Desktop browser notifications when a message arrives (requires user permission)
Clicking a notification opens the relevant chat directly
Browser tab title flashes with the sender name when the window is not focused

3.7 Admin Panel

public/admin.html · server.js

Separate password-protected dashboard at /admin.html
Stats bar: total users, complete profiles, users with photos, total messages
Users tab: searchable table with all fields and a delete button per row
Messages tab: full log with sender, receiver, content, timestamp; delete per row
Refresh button reloads live data without a page reload
One-click link to Error Logs page
Syncs directly with the live Supabase database — manage users and messages without ever opening the Supabase dashboard

3.8 Error Logging

logger.js · server.js · public/logs.html

All uncaught exceptions and unhandled promise rejections are written to error.log
Route errors, failed login attempts, and admin login events are also logged
Admin-only /api/logs endpoint to read the log file
Admin-only DELETE /api/logs to clear the log
Dedicated log viewer at /logs.html with dark terminal theme
Auto-refresh every 5 seconds - no page reload needed
Color-coded entries: INFO (green), WARN (amber), ERROR (red) with full stack traces

3.9 Contact Form

public/profile.html · server.js

Send Message button on the Profile page opens a modal contact form
Fields: Your Name, Subject, Message (1000-character limit with counter)
Messages are sent via Formspree API to the developer's email
Success confirmation on submission, auto-closes after 2 seconds
No login required to submit - accessible to all authenticated users

4. API Endpoints

All routes are relative to http://localhost:3000. Auth = Bearer token required. Admin = admin JWT required.

Method	Route	Auth?	Description
POST	/api/register	No	Create a new account
POST	/api/login	No	Login - returns JWT + userId
POST	/api/forgot-password	No	Verify email exists, return reset token (15 min TTL)
POST	/api/reset-password	No	Set new password using reset token
PUT	/api/change-password	Yes	Change password (current password required)
PUT	/api/profile	Yes	Update profile fields + optional photo upload
GET	/api/profile/me	Yes	Get own profile data
GET	/api/members	Yes	List all members with complete profiles
GET	/api/messages/:otherId	Yes	Message history with another user
GET	/api/conversations	Yes	Conversation list with last-message preview
POST	/api/chat/upload	Yes	Upload a file for use in chat
POST	/api/admin/login	No	Admin login - returns admin JWT
GET	/api/admin/users	Admin	All users (passwords excluded)
GET	/api/admin/messages	Admin	Full message log with sender/receiver names
GET	/api/admin/stats	Admin	Aggregate stats (users, messages, etc.)
DELETE	/api/admin/users/:id	Admin	Delete user and all their messages
DELETE	/api/admin/messages/:id	Admin	Delete a single message
GET	/api/logs	Admin	Read the server error log file
DELETE	/api/logs	Admin	Clear the error log file

5. Socket Events

Real-time messaging uses Supabase Realtime (PostgreSQL logical replication). No persistent WebSocket connections needed.

The following events are handled via REST API endpoints and Supabase Realtime subscriptions:

Event	Direction	Payload Fields	Description
send_message	Client → Server	receiverId, content, type, fileName	Send message; server saves + routes it
new_message	Server → Client	id, sender_id, receiver_id, content, type, sender_name	Delivered to sender and receiver
edit_message	Client → Server	messageId, content	Edit own message
message_edited	Server → Client	messageId, content	Both parties update the message text
delete_message	Client → Server	messageId	Delete own message
message_deleted	Server → Client	messageId	Both parties remove the message
user_status	Server → All	userId, online, lastSeen	Emitted on every connect / disconnect

6. File Structure

Path	Purpose
Code App/	-- project root
server.js	Express API + Logger (all backend logic)
logger.js	Error logging module - writes timestamped entries to error.log
error.log	Auto-generated log file (created at runtime)
database.js	Supabase client setup - exports @supabase/supabase-js instance
db.json	Legacy JSON database (fully migrated to Supabase — kept for reference only)
generate_docs.js	Script to regenerate this documentation
package.json	npm dependency manifest
public/	-- static frontend files served by Express
index.html	Login, Register, Forgot Password
profile.html	Profile editing + Change Password
browse.html	Discover member grid
chat.html	Real-time chat UI
admin.html	Admin dashboard
logs.html	Error log viewer (admin-only, auto-refresh)
documentation.html	This page - technical documentation
nav.js	Shared navbar chip (name + avatar)
global.js	Presence heartbeat, Supabase Realtime notifications, tab-title flash
style.css	All styles for all pages
uploads/	Profile photos + chat files (exclude from git)

7. Credentials & Configuration

Setting	Value	Where to change
Server port	3000	server.js - const PORT
JWT secret	social-app-secret-key-change-in-prod	server.js - const JWT_SECRET
JWT expiry	7 days	server.js - jwt.sign expiresIn
Admin password	admin1234	server.js - const ADMIN_PASSWORD
Profile photo limit	5 MB	server.js - upload multer config
Chat file limit	10 MB	server.js - uploadChat multer config
Database	Supabase PostgreSQL	database.js - Supabase client config
Supabase URL	http://127.0.0.1:54321	Local Supabase API endpoint
Supabase Studio	http://127.0.0.1:54323	Web UI for database management

Security note: Change JWT_SECRET and ADMIN_PASSWORD before deploying to any public server.

8. Data Models (Supabase PostgreSQL)

User

Field	Type	Description
id	number	Auto-incrementing primary key
username	string	Unique; chosen at registration
email	string	Unique email address
password	string	bcrypt hash - never returned by any API route
name	string \| null	Display name set on Profile page
age	number \| null	Age set on Profile page
gender	string \| null	Gender set on Profile page
bio	string \| null	Short bio, max 300 characters
photo	string \| null	Server path, e.g. /uploads/photo.jpg
created_at	ISO string	Registration timestamp
lastSeen	ISO string	Updated via heartbeat every 30-45s + on tab close/logout

Message

Field	Type	Description
id	number	Auto-incrementing primary key
sender_id	number	ID of the sending user
receiver_id	number	ID of the recipient
content	string	Message text or /uploads/... path for files
type	"text" \| "image" \| "file"	Defaults to "text"
fileName	string \| null	Original filename for attachments
edited	boolean	true if the sender edited this message
created_at	ISO string	Send timestamp (server time)

9. Reasonix Setup

Reasonix is a DeepSeek-native coding agent that runs in the terminal. It's designed around DeepSeek's API directly - cache-first loop, flash-first cost control, and automatic tool-call repair.

Prerequisites

Node.js 20.10+ - verify with node --version
DeepSeek API key - obtain from platform.deepseek.com under API Keys
Git for Windows (Windows users only)

Step-by-Step Setup

Open Command Prompt - press Win + R, type cmd, press Enter
Navigate to project folder - cd C:\Users\andre\Documents\Deepseek\Code App
Run Reasonix - npx reasonix@latest code (first run prompts for your API key)
Enter your API key when prompted - it's saved automatically to C:\Users\andre\.reasonix\config.json
(Optional) Customise config - notepad C:\Users\andre\.reasonix\config.json

Cost Comparison

Model	Cost / Turn	Turns for $4.98	Best For
Flash (default)	~$0.0006	~8,000	Quick edits, exploration
Pro (`/preset max`)	~$0.01–0.03	~200	Complex reasoning tasks

Key Commands

Shortcut / Command	Action
`Ctrl + L`	Clear terminal
`Ctrl + C`	Exit Reasonix
`Shift + Tab`	Auto-apply all suggestions
`y / n`	Accept or discard a change
`/preset max`	Switch to DeepSeek Pro model
`/stats`	Show token/cost statistics
`/cost`	Show running cost
`/clear`	Clear conversation context
`/help`	Show all commands

Tip: Use Flash for quick exploration and iterative work; switch to Pro with /preset max when you need deep reasoning. In v0.28.0, the model/preset fields in config.json are ignored - you must run /preset max manually each session.

Quick-Start Cheat Sheet

Every session, run these four lines:

cd C:\Users\andre\Documents\Deepseek\Code App npx reasonix@latest code /preset max /stats

10. Supabase Local Setup

Spark has migrated from lowdb (JSON file) to Supabase (PostgreSQL) for better scalability and Vercel deployment readiness.

Prerequisites

Docker Desktop - install from docker.com
Supabase CLI - installed via npx (no global install needed)

Local Setup

cd C:\Users\andre\Documents\Deepseek\Code App npx supabase init npx supabase start

This spins up PostgreSQL + Supabase Studio + all supporting services locally via Docker.

Local URLs

Service	URL
Supabase Studio (web UI)	http://127.0.0.1:54323
API Endpoint	http://127.0.0.1:54321
Database URL	postgresql://postgres:postgres@127.0.0.1:54322/postgres
Mailpit (test emails)	http://127.0.0.1:54324

Cloud Supabase

Spark uses a cloud Supabase project (CWD) at https://hpezaqvtufrvvczyixwc.supabase.co for production data. The local Supabase instance is used for development and testing.

Migration Complete

All phases completed! Spark now runs entirely on Supabase PostgreSQL.

Phase 1 - Set up Supabase locally ✅
Phase 2 - Create tables (users, messages, contacts) ✅
Phase 3 - Migrated 5 users, 19 messages, 2 contacts from db.json ✅
Phase 4 - Replaced all lowdb queries with Supabase ✅
Phase 5 - File uploads moved to Supabase Storage ✅
Phase 6 - Deploy to Vercel ✅ - live at cebuspark.com

11. Database Access

Access your Supabase PostgreSQL database two ways:

Supabase Dashboard (Web UI)

Go to supabase.com/dashboard
Sign in with GitHub, select the CWD project
Table Editor - browse/edit users, messages, contacts
SQL Editor - run custom queries
Storage - manage uploaded files

Direct PostgreSQL Connection

Setting	Value
Host	aws-0-ap-southeast-1.pooler.supabase.com
Port	6543
Database	postgres
Username	postgres.hpezaqvtufrvvczyixwc
Password	Database password set during project creation

Contents

1. Tech Stack

2. How to Run

Prerequisites

First-time setup

Start the server

Open in browser

3. Features

3.1 Authentication

3.2 Profile

3.3 Discover / Browse

3.4 Real-Time Chat

3.5 Online / Offline Presence

3.6 Unread Badges & Browser Notifications

3.7 Admin Panel

3.8 Error Logging

3.9 Contact Form

4. API Endpoints

5. Socket Events

6. File Structure

7. Credentials & Configuration

8. Data Models (Supabase PostgreSQL)

User

Message

9. Reasonix Setup

Prerequisites

Step-by-Step Setup

Cost Comparison

Key Commands

Quick-Start Cheat Sheet

10. Supabase Local Setup

Prerequisites

Local Setup

Local URLs

Cloud Supabase

Migration Complete

11. Database Access

Supabase Dashboard (Web UI)

Direct PostgreSQL Connection