# Meshagora

A social platform simulator for teaching digital literacy. Runs as a local web server on an Android phone (via Termux), participants join through their browsers over WiFi — no internet required, no app install, no persistent data.

Designed for workshop facilitation. Every session starts clean. All data lives in memory and is destroyed when the server stops.

---

## What it teaches

Meshagora recreates the mechanics of real social platforms in a controlled, observable environment:

- Tiered posting access (who gets amplified, who gets restricted)
- Pseudonymity vs. identity (session labels vs. confirmed friends)
- Community reporting and auto-restriction
- Algorithmic feed ordering (invisible vote weights)
- Handshake-based friend networks and friends-only feeds
- Flood attacks (bot accounts)
- Admin surveillance — the platform sees everything participants don't

---

## Requirements

```
Python 3.8+
flask
qrcode[pil]
```

---

## Quick Start — Termux (Android, recommended for sessions)

```bash
pkg install python git
pip install flask qrcode[pil]
git clone https://github.com/JL-Kruger/meshagora.git
cd meshagora
```

1. Enable the Android **mobile hotspot** before running the script.
2. Run:
   ```bash
   python3 meshagora.py
   ```
3. The startup banner prints the join URL, QR code link, and all post keys.
4. Participants connect to the hotspot WiFi and open the join URL in any browser.

See `DEPLOY.md` for the full pre-session checklist, admin panel guide, and troubleshooting.

---

## Quick Start — Desktop (testing)

```bash
pip install flask qrcode[pil]
python3 meshagora.py
```

Server runs at `http://127.0.0.1:5000`. Open multiple browser tabs or incognito windows to simulate multiple participants.

---

## Architecture

Single-file Flask application (`meshagora.py`). No framework, no database file, no external assets. SQLite runs in-memory. `threaded=False` is mandatory — do not change it.

### Post tiers

| Tier | Key length | Who has it |
|---|---|---|
| ADMIN | 4 emoji | Facilitator only |
| TRUSTED | 2 emoji | Promoted users |
| DEFAULT | 2 emoji | All registered users (rotates on restriction events) |
| RESTRICTED | co-sign | Users restricted by admin or community report |

### Feed ordering

1. Highest-score post pinned to top
2. Middle posts ordered newest-first
3. Lowest-score post pinned to bottom

### Auto-restriction

When unique reporters exceed 51% of a user's total posts, that user is automatically restricted and the Default Post Key rotates silently.

---

## Files

| File | Purpose |
|---|---|
| `meshagora.py` | Complete implementation |
| `meshagora_spec_v2_3.md` | Full design specification |
| `DEPLOY.md` | Deployment guide, troubleshooting, pre-session checklist |

---

## Stopping the Server

`Ctrl+C` in the terminal. All session data is gone immediately. This is intentional.