Beacon

A location-based social network.

Warning

This project is under active development and is not yet ready for production use.

Documentation

Setup

1. Install dependencies

• NodeJS (LTS recommended)
• Git
• If running Supabase locally:
  • Docker/Docker Engine

2. Clone the repository:

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

3. Inside the repository, install the dependencies:

npm install

4. If you want to run Supabase locally, start the Docker container:

# This can take a while the first time you run it because it has to download a bunch of Docker images
npm run supabase:start

# Check the status of the Supabase (Including the dashboard URL and mock email server URL)
npm run supabase:status

5. Update .env with the appropriate values (See Frontend Environment Variables).

6. Still inside the repository, start the development server:

npm run dev

7. Open http://localhost:3000 in your browser to access the frontend

8. If running Supabase locally, reset the database after each schema change:

npm run supabase:reset

Production

Build

To build the frontend for production, run:

docker build -t beacon -f Dockerfile .

Run

To run the frontend in production, run:

docker run -p 80:8080 beacon

Frontend Environment Variables

Development Name (i.e.: not in the container)	Production Name (i.e.: in the container)	Description	Default/Required
VITE_HCAPTCHA_SITE_KEY	CADDY_HCAPTCHA_SITE_KEY	The hCaptcha site key	Required ( ⚠️ Must be manually set ⚠️; see hCaptcha dashboard)
VITE_SUPABASE_URL	CADDY_SUPABASE_URL	The absolute Supabase API URL	Required (Automatically set by the setup script)
VITE_SUPABASE_ANON_KEY	CADDY_SUPABASE_ANON_KEY	The Supabase API anonymous key	Required (Automatically set by the setup script)
VITE_SENTRY_DSN	CADDY_SENTRY_DSN	The Sentry DSN	Optional (Automatically set by the setup script)

Technologies

• Frontend
  • Language: TypeScript
  • Web framework: React + Vite
  • Component library: Ionic React
  • Styling: UnoCSS (Wind preset) (Tailwind/WindiCSS compatible)
• Backend: Supabase

Algorithm

Beacon's ranking algorithm is somewhat inspired by the Lemmy algorithm, but has the following properties:

Description	Reasoning
Quadratic distance contribution	Posts that are closer to the user should have a higher rank. This helps users see posts that are more geographically relevant to them.
Logarithmic score contribution	The first $10$, next $100$, next $1000$, etc. votes should have the same contribution to the rank. This helps counteract the bandwagon effect.
Exponential age reduction	The older a post is, the less relevant it likely is. This helps newer posts rank higher.

The algorithm is as follows:

$$\text{Distance component}=(\text{Distance weight}-1)\cdot (min(1,\frac{\text{Distance}}{\text{Distance range}})-1{)}^2+1$$

$$\text{Score component}={\log }_{10}(max(1,(\text{Upvotes}-\text{Downvotes})-\text{Score threshold}+1))$$

$$\text{Age component}={\text{Age weight}}^{-\text{Age}}$$

$$\text{Rank}=\lfloor (\text{Scale}\cdot \text{Distance component}\cdot \text{Score component}\cdot \text{Age component}\rfloor$$

with the following variables:

Name	Definition	Min value	Default value	Max value
$\text{Rank}$	Integer post sorting order (Higher will be sorted first)	-	-	-
$\text{Scale}$	Ranking scale factor (To allow the rank to be rounded)	$1$ (Don't rank)	$10000$	-
$\text{Distance}$	Distance between the post and the user's location (In meters)	-	-	-
$\text{Distance weight}$	Distance weight factor	$1$ (Don't rank by distance)	$5$	-
$\text{Distance range}$	Maximum distance to be considered (In meters)	$1$	$5000$	$50000$
$\text{Upvotes}$	Post upvotes	-	-	-
$\text{Downvotes}$	Post downvotes	-	-	-
$\text{Score threshold}$	Minimum score threshold considered	$-5$	$-5$	-
$\text{Age}$	Post age (In hours)	-	-	-
$\text{Age weight}$	Age weight factor	$1$ (Don't weight by age)	$1.075$	-