mhreteabeTD/ethiopian-trivia-game
Record type:
software
Creator:
mhr
Host:
# Ethiopian Celebrity Trivia
Telegram Mini App trivia game focused on Ethiopian celebrities. Bilingual (Amharic primary, English secondary).
## Stack
- **Frontend**: React (Vite) + Telegram Web App SDK — Vercel
- **Backend**: Python FastAPI + WebSockets — Render
- **Bot**: python-telegram-bot v20+
- **Database**: SQLite + SQLAlchemy
## Project structure
```
├── bot/ Telegram bot (/start → Mini App)
├── backend/ FastAPI API + WebSocket
├── frontend/ React Mini App
├── games/ Plugin-style game modules
├── assets/ Celebrity and mashup images
└── data/ Shared celebrity JSON
```
## Environment variables
Copy `.env.example` to `.env` at the repo root:
| Variable | Used by | Description |
|----------|---------|-------------|
| `BOT_TOKEN` | bot, backend | Telegram bot token |
| `WEBAPP_URL` | bot, CORS | HTTPS Mini App URL (Vercel) |
| `DATABASE_URL` | backend | e.g. `sqlite:///./trivia.db` |
| `VITE_API_URL` | frontend | REST API base URL |
| `VITE_WS_URL` | frontend | WebSocket base URL |
| `TELEGRAM_BOT_USERNAME` | optional | Bot username |
| `ENV` | backend | `development` or `production` |
| `CORS_ORIGINS` | backend | Extra origins (comma-separated) |
| `INIT_DATA_MAX_AGE_SECONDS` | backend | initData max age (default 86400) |
## Install dependencies
### Python
```bash
pip install -r backend/requirements.txt
pip install -r bot/requirements.txt
```
### Node (frontend)
```bash
cd frontend && npm install
```
## Local development
1. Set `.env` with `BOT_TOKEN`, `WEBAPP_URL` (use ngrok or Telegram test URL for Mini App).
2. **Backend** (from repo root):
```bash
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
```
Health: `GET localhost`
3. **Frontend**:
```bash
cd frontend && npm run dev
```
4. **Bot**:
```bash
python -m bot.main
```
5. **Seed database** (optional):
```bash
python -m backend.db.seed
```
## Mashup image generator
Requires Pillow. Place celebrity photos in ` …