HKSingleParty/99_references/beacon-main

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\bigg(1, \frac{\text{Distance}}{\text{Distance range}}\bigg) - 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	-