Vatoring

A GitHub-style Telegram Mini App for monitoring your Git repositories and tasks.

It shows your GitHub and GitLab repositories with metadata (language, stars, forks, visibility, last update), CI status (GitHub Actions / GitLab pipelines), and the issues / pull requests assigned to you. The profile is authenticated with Telegram, and access tokens are entered in-app and stored on the server per Telegram user.

Features

• Real data from GitHub and GitLab (no mocks once a token is set).
• Repository list styled after GitHub's repositories page (Primer): blue title links, Public/Private labels, language color dots, ★/⑂ counts, "Updated …".
• CI status next to each repo: ✓ passed / ✗ failed / ● in progress.
• Issues — open issues and MRs assigned to the user.
• Telegram-authenticated profile (#profile) — the signed-in Telegram identity (name, @username, avatar) is verified server-side from the Mini App initData; GitHub/GitLab Personal Access Tokens are entered here and stored per Telegram user.
• Themes (light/dark, synced with the Telegram theme) and languages (RU/EN).
• Telegram bot with commands and a button to launch the Mini App.

Architecture

• api/ — FastAPI: REST endpoints, GitHub/GitLab clients, serves the built Mini App.
• bot/ — Aiogram: Telegram bot, proxies commands to the API, stateless.
• frontend/miniapp/ — React + Vite: the Mini App UI.
• infra/ — Docker Compose (api, bot, Postgres, Redis) for local runs.

Data flow: Mini App / bot → API → GitHub & GitLab APIs. The Mini App sends the Telegram initData (header X-Telegram-Init-Data); the API validates it against BOT_TOKEN and resolves provider tokens with the precedence request header → per-user store (by Telegram id) → environment. With no tokens at all, the API returns demo data.

API

Method	Path	Description
GET	/health	Liveness check.
GET	/repos	Repositories (GitHub + GitLab), sorted.
GET	/tasks	Assigned issues / MRs.
GET	/me	Telegram user + connected provider accounts.
POST	/tokens	Save GitHub/GitLab tokens (requires Telegram auth).
—	/miniapp/	Built Mini App static files (when dist exists).

Data endpoints read the Telegram session from the X-Telegram-Init-Data header and may also accept X-GitHub-Token / X-GitLab-Token headers, which override stored/env tokens.

Environment variables

Copy .env.example to .env in the repository root and fill in what you need:

Variable	Purpose
API_HOST, API_PORT	API host/port (default 0.0.0.0:8000).
API_BASE_URL	Base API URL used by the bot.
LOG_LEVEL	uvicorn log level.
MINIAPP_DIST_DIR	Override the built Mini App path (default frontend/miniapp/dist).
BOT_TOKEN	Telegram bot token (BotFather); also used by the API to validate initData.
WEBAPP_URL	Public HTTPS URL of the Mini App — enables the button and /app.
GITHUB_TOKEN	GitHub PAT (scope repo or public_repo) — fallback for the profile.
GITLAB_TOKEN	GitLab PAT (scope read_api) — fallback for the profile.
WATCHLIST	owner/repo,group/project list to filter repositories.
DATABASE_URL, REDIS_URL	Reserved for future use (DB/cache), currently unused.

Set provider tokens inside the app (the "Profile" screen). When opened in Telegram they are stored on the server, keyed by your Telegram id (plaintext JSON at api/.tokens.json, gitignored), and loaded automatically on any device. Opened in a plain browser (no Telegram session) the profile falls back to keeping tokens in localStorage. GITHUB_TOKEN / GITLAB_TOKEN in .env remain a server-side fallback (e.g. for the bot's /repos command).

Quick start (local, without Docker)

Requires Python 3.11+ and Node.js 18+.

1. Set up the Python environment and dependencies:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r api\requirements.txt -r bot\requirements.txt

2. Prepare the config: copy .env.example → .env (tokens may stay empty — you'll see demo data and can add a token later in the profile).
3. Start the API (from the repo root):

   .\.venv\Scripts\python -m uvicorn api.main:app --host 127.0.0.1 --port 8000 --reload

   If port 8000 is taken, use another one (e.g. --port 8001) and set it in frontend/miniapp/.env → API_BASE_URL.

4. Start the Mini App (in a separate terminal):

   cd frontend\miniapp
   npm install
   npm run dev

   Open http://localhost:5173. The API has CORS open for development.
5. (Optional) start the bot:

   .\.venv\Scripts\python bot\bot.py

Mini App

• Code: frontend/miniapp (React + Vite + TypeScript).
• The API URL is set in frontend/miniapp/.env (API_BASE_URL); in production, when the API serves the static files itself, leave it empty so requests use a relative path on the same origin.
• Scripts:
  • npm run dev — dev server with hot reload.
  • npm run build — production build into frontend/miniapp/dist (served by the API at /miniapp/).
  • npm run preview — preview the production build.

Telegram bot

Commands: /start, /app (open the Mini App), /repos (list from the API), /tasks. The menu button and /app command appear only when WEBAPP_URL is set.

Running inside Telegram

Telegram opens the Mini App on a phone, so localhost won't work — you need a public HTTPS URL, and it's easiest to keep the Mini App and the API on the same origin.

1. In frontend/miniapp/.env leave API_BASE_URL= empty and build: npm run build.
2. Start the API (it serves both /miniapp/ and the data endpoints on one port).
3. Expose an HTTPS tunnel to the API port, e.g.:

   .\cloudflared.exe tunnel --url http://localhost:8000
   # or: ngrok http 8000

4. Set WEBAPP_URL=https://<tunnel>/miniapp/ in .env and start the bot.
5. In Telegram open the bot → the menu button next to the input field / the /app command.

Quick tunnels hand out a new URL on every launch — after a restart, update WEBAPP_URL and restart the bot.

Deploying to Railway

The repo ships with api.Dockerfile (multi-stage: builds the mini app, serves it together with the API from one port, honours Railway's PORT).

1. Push the repo to GitHub and create a Railway project from it.
2. API service: in Settings → Build set Dockerfile Path = api.Dockerfile (root directory stays /). Generate a public domain in Settings → Networking.
3. Attach a volume mounted at /data — the per-user token store lives at /data/tokens.json (set via TOKENS_FILE in the image); without a volume user tokens reset on every deploy.
4. Service variables: BOT_TOKEN (required — validates Telegram initData). Do not set GITHUB_TOKEN/GITLAB_TOKEN here: they would act as a global fallback for anonymous requests.
5. Bot service (optional): add a second service from the same repo with Root Directory = bot. Variables: BOT_TOKEN, API_BASE_URL = the API service's public URL, WEBAPP_URL = <API URL>/miniapp/.
6. Point BotFather at the permanent URL: menu button / Mini App URL = https://<api-domain>/miniapp/.

Running with Docker

cd infra
docker compose up --build

This brings up Postgres, Redis, the API (:8000) and the bot. Variables are read from the root .env.

Repository layout

• api/main.py — FastAPI app: provider aggregation, token resolution, serving the Mini App.
• api/providers.py — async GitHub/GitLab clients (repos, tasks, account) with retries.
• api/telegram_auth.py — Telegram initData validation.
• api/token_store.py — per-user token storage keyed by Telegram id.
• bot/bot.py — Telegram bot (Aiogram).
• frontend/miniapp/src/ — Mini App sources (App.tsx, style.css, types.ts).
• infra/docker-compose.yml, */Dockerfile — containerization.
• .env.example — environment variable contract.

Next steps

• Cache provider responses (Redis) and add background polling with Telegram alerts.
• Accept GitHub/GitLab webhooks instead of polling.
• Wire up a database (Postgres/SQLAlchemy) for history and settings.
• Tests for the API contracts and bot handlers.