stage 1

.env.example

@@ -0,0 +1,7 @@
+# Local dev only. On Hugging Face put these in Settings -> Secrets. NEVER commit .env
+BOT_TOKEN=123456:ABC...
+DATABASE_URL=postgresql://USER:PASSWORD@HOST:6543/postgres
+GATE_CHANNEL=@DBUCentral
+ADMIN_IDS=111111,222222
+DEFAULT_LANG=am
+LOG_LEVEL=INFO

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.env
+dev.db

app.py

@@ -0,0 +1,33 @@
+"""Hugging Face Space entrypoint (Gradio SDK).
+
+Gradio only serves a tiny status page (also used for uptime pings).
+The Telegram bot runs in a background thread.
+"""
+import asyncio
+import threading
+
+import gradio as gr
+
+try:  # ZeroGPU Spaces expect at least one @spaces.GPU function
+    import spaces
+
+    @spaces.GPU
+    def _noop():
+        return "ok"
+except ImportError:  # running locally
+    pass
+
+from app.main import run_bot_forever
+
+
+def _runner() -> None:
+    asyncio.run(run_bot_forever())
+
+
+threading.Thread(target=_runner, daemon=True, name="telegram-bot").start()
+
+with gr.Blocks(title="DBU Central Bot") as demo:
+    gr.Markdown("### DBU Central Bot is running ✅")
+
+if __name__ == "__main__":
+    demo.launch()

app/bot/handlers/__init__.py

@@ -0,0 +1,11 @@
+from aiogram import Router
+
+from app.bot.handlers import gate, menu, start
+
+
+def build_router() -> Router:
+    router = Router()
+    router.include_router(gate.router)
+    router.include_router(start.router)
+    router.include_router(menu.router)
+    return router

app/bot/handlers/gate.py

@@ -0,0 +1,25 @@
+from aiogram import F, Router
+from aiogram.types import CallbackQuery
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.bot.handlers.start import next_step
+from app.core.i18n import t
+from app.db.models import User
+from app.services import gate
+from app.services import referrals as referral_service
+
+router = Router()
+
+
+@router.callback_query(F.data == "gate:check")
+async def gate_check(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    if not await gate.is_member(call.bot, user.id, fresh=True):
+        await call.answer(t(user.lang, "gate_not_yet"), show_alert=True)
+        return
+    await call.answer()
+    if not user.gate_passed:
+        user.gate_passed = True
+        await referral_service.reward_if_eligible(session, call.bot, user)
+    if call.message:
+        await call.message.delete()
+        await next_step(call.message, user)

app/bot/handlers/menu.py

@@ -0,0 +1,29 @@
+from aiogram import F, Router
+from aiogram.types import Message
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.bot.keyboards.common import main_menu
+from app.core.i18n import all_translations, t
+from app.db.models import User
+from app.services import referrals as referral_service
+
+router = Router()
+
+
+@router.message(F.text.in_(all_translations("btn_library") | all_translations("btn_gpa")))
+async def coming_soon(message: Message, user: User) -> None:
+    await message.answer(t(user.lang, "soon"))
+
+
+@router.message(F.text.in_(all_translations("btn_invite")))
+async def invite(message: Message, user: User, session: AsyncSession) -> None:
+    me = await message.bot.me()
+    count, points = await referral_service.stats(session, user)
+    link = f"https://t.me/{me.username}?start={user.id}"
+    await message.answer(t(user.lang, "invite_text", link=link, count=count, points=points))
+
+
+@router.message(F.text.in_(all_translations("btn_lang")))
+async def toggle_lang(message: Message, user: User) -> None:
+    user.lang = "en" if user.lang == "am" else "am"
+    await message.answer(t(user.lang, "lang_changed"), reply_markup=main_menu(user.lang))

app/bot/handlers/start.py

@@ -0,0 +1,53 @@
+from aiogram import F, Router
+from aiogram.filters import CommandStart
+from aiogram.types import CallbackQuery, Message
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.bot.keyboards.common import main_menu, stream_kb, year_kb
+from app.core.catalog import STREAMS, YEARS
+from app.core.i18n import t
+from app.db.models import User
+
+router = Router()
+
+
+async def next_step(message: Message, user: User) -> None:
+    """Send whichever onboarding step is still missing, else the main menu."""
+    lang = user.lang
+    if user.stream is None:
+        await message.answer(t(lang, "choose_stream"), reply_markup=stream_kb(lang))
+    elif user.year is None:
+        await message.answer(t(lang, "choose_year"), reply_markup=year_kb(lang))
+    else:
+        await message.answer(t(lang, "menu_title"), reply_markup=main_menu(lang))
+
+
+@router.message(CommandStart())
+async def cmd_start(message: Message, user: User) -> None:
+    await message.answer(t(user.lang, "welcome", name=message.from_user.full_name))
+    await next_step(message, user)
+
+
+@router.callback_query(F.data.startswith("ob:stream:"))
+async def pick_stream(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    value = call.data.split(":")[2]
+    if value in STREAMS:
+        user.stream = value
+    await call.answer()
+    if call.message:
+        await call.message.delete()
+        await next_step(call.message, user)
+
+
+@router.callback_query(F.data.startswith("ob:year:"))
+async def pick_year(call: CallbackQuery, user: User, session: AsyncSession) -> None:
+    value = call.data.split(":")[2]
+    if value.isdigit() and int(value) in YEARS:
+        user.year = int(value)
+    await call.answer()
+    if call.message:
+        await call.message.delete()
+        if user.year is not None:
+            await call.message.answer(t(user.lang, "onboarded"), reply_markup=main_menu(user.lang))
+        else:
+            await next_step(call.message, user)

app/bot/keyboards/common.py

@@ -0,0 +1,46 @@
+from aiogram.types import (
+    InlineKeyboardButton,
+    InlineKeyboardMarkup,
+    KeyboardButton,
+    ReplyKeyboardMarkup,
+)
+
+from app.core.catalog import STREAMS, YEARS
+from app.core.i18n import t
+
+
+def gate_kb(lang: str, url: str) -> InlineKeyboardMarkup:
+    return InlineKeyboardMarkup(
+        inline_keyboard=[
+            [InlineKeyboardButton(text=t(lang, "gate_join_btn"), url=url)],
+            [InlineKeyboardButton(text=t(lang, "gate_check_btn"), callback_data="gate:check")],
+        ]
+    )
+
+
+def stream_kb(lang: str) -> InlineKeyboardMarkup:
+    return InlineKeyboardMarkup(
+        inline_keyboard=[
+            [InlineKeyboardButton(text=t(lang, f"stream_{s}"), callback_data=f"ob:stream:{s}")]
+            for s in STREAMS
+        ]
+    )
+
+
+def year_kb(lang: str) -> InlineKeyboardMarkup:
+    buttons = [
+        InlineKeyboardButton(text=t(lang, "year_label", n=y), callback_data=f"ob:year:{y}")
+        for y in YEARS
+    ]
+    return InlineKeyboardMarkup(inline_keyboard=[buttons[:3], buttons[3:]])
+
+
+def main_menu(lang: str) -> ReplyKeyboardMarkup:
+    return ReplyKeyboardMarkup(
+        keyboard=[
+            [KeyboardButton(text=t(lang, "btn_library"))],
+            [KeyboardButton(text=t(lang, "btn_gpa")), KeyboardButton(text=t(lang, "btn_invite"))],
+            [KeyboardButton(text=t(lang, "btn_lang"))],
+        ],
+        resize_keyboard=True,
+    )

app/bot/loader.py

@@ -0,0 +1,16 @@
+from aiogram import Dispatcher
+
+from app.bot.handlers import build_router
+from app.bot.middlewares.context import ContextMiddleware
+from app.bot.middlewares.gate import GateMiddleware
+from app.bot.middlewares.throttle import ThrottleMiddleware
+
+
+def build_dispatcher() -> Dispatcher:
+    dp = Dispatcher()
+    for observer in (dp.message, dp.callback_query):
+        observer.middleware(ThrottleMiddleware())
+        observer.middleware(ContextMiddleware())  # must come before the gate
+        observer.middleware(GateMiddleware())
+    dp.include_router(build_router())
+    return dp

app/bot/middlewares/context.py

@@ -0,0 +1,33 @@
+from typing import Any, Awaitable, Callable, Optional
+
+from aiogram import BaseMiddleware
+from aiogram.types import Message, TelegramObject
+
+from app.db.session import SessionFactory
+from app.services import users as users_service
+
+
+def _referrer_from(event: TelegramObject) -> Optional[int]:
+    if isinstance(event, Message) and event.text and event.text.startswith("/start"):
+        parts = event.text.split(maxsplit=1)
+        if len(parts) == 2 and parts[1].isdigit():
+            return int(parts[1])
+    return None
+
+
+class ContextMiddleware(BaseMiddleware):
+    """One DB session per update + the current `user` and `lang` injected into handlers."""
+
+    async def __call__(self, handler: Callable[[TelegramObject, dict], Awaitable[Any]],
+                       event: TelegramObject, data: dict) -> Any:
+        tg = data.get("event_from_user")
+        if tg is None or tg.is_bot:
+            return await handler(event, data)
+        async with SessionFactory() as session:
+            user = await users_service.get_or_create(session, tg, _referrer_from(event))
+            data.update(session=session, user=user, lang=user.lang)
+            if user.is_banned:
+                return None
+            result = await handler(event, data)
+            await session.commit()
+            return result

app/bot/middlewares/gate.py

@@ -0,0 +1,32 @@
+from typing import Any, Awaitable, Callable
+
+from aiogram import BaseMiddleware
+from aiogram.types import CallbackQuery, Message, TelegramObject
+
+from app.bot.keyboards.common import gate_kb
+from app.config import get_settings
+from app.core.i18n import t
+from app.services import gate
+
+
+class GateMiddleware(BaseMiddleware):
+    async def __call__(self, handler: Callable[[TelegramObject, dict], Awaitable[Any]],
+                       event: TelegramObject, data: dict) -> Any:
+        tg = data.get("event_from_user")
+        user = data.get("user")
+        if tg is None or user is None or tg.id in get_settings().admin_id_set:
+            return await handler(event, data)
+        if isinstance(event, CallbackQuery) and event.data == "gate:check":
+            return await handler(event, data)
+        if await gate.is_member(data["bot"], tg.id):
+            return await handler(event, data)
+
+        lang = user.lang
+        text, kb = t(lang, "gate_text"), gate_kb(lang, gate.channel_url())
+        if isinstance(event, Message):
+            await event.answer(text, reply_markup=kb)
+        elif isinstance(event, CallbackQuery):
+            await event.answer()
+            if event.message:
+                await event.message.answer(text, reply_markup=kb)
+        return None

app/bot/middlewares/throttle.py

@@ -0,0 +1,25 @@
+import time
+from typing import Any, Awaitable, Callable
+
+from aiogram import BaseMiddleware
+from aiogram.types import TelegramObject
+
+
+class ThrottleMiddleware(BaseMiddleware):
+    """Drop updates from a user who sends faster than `interval` seconds apart."""
+
+    def __init__(self, interval: float = 0.5) -> None:
+        self.interval = interval
+        self._last: dict[int, float] = {}
+
+    async def __call__(self, handler: Callable[[TelegramObject, dict], Awaitable[Any]],
+                       event: TelegramObject, data: dict) -> Any:
+        tg = data.get("event_from_user")
+        if tg:
+            now = time.monotonic()
+            if now - self._last.get(tg.id, 0) < self.interval:
+                return None
+            self._last[tg.id] = now
+            if len(self._last) > 50_000:
+                self._last.clear()
+        return await handler(event, data)

app/config.py

@@ -0,0 +1,23 @@
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    bot_token: str
+    database_url: str = "sqlite+aiosqlite:///./dev.db"
+    gate_channel: str = "@DBUCentral"
+    admin_ids: str = ""  # comma separated Telegram user ids
+    default_lang: str = "am"
+    log_level: str = "INFO"
+
+    @property
+    def admin_id_set(self) -> set[int]:
+        return {int(x) for x in self.admin_ids.replace(" ", "").split(",") if x.isdigit()}
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

app/core/catalog.py

@@ -0,0 +1,3 @@
+# Placeholder catalog. Extend later (departments, semesters...).
+STREAMS = ("natural", "social")
+YEARS = (1, 2, 3, 4, 5)

app/core/i18n.py

@@ -0,0 +1,24 @@
+import json
+from pathlib import Path
+
+_LOCALES_DIR = Path(__file__).resolve().parents[2] / "locales"
+SUPPORTED = ("am", "en")
+_cache: dict[str, dict[str, str]] = {}
+
+
+def _load(lang: str) -> dict[str, str]:
+    if lang not in _cache:
+        with open(_LOCALES_DIR / f"{lang}.json", encoding="utf-8") as f:
+            _cache[lang] = json.load(f)
+    return _cache[lang]
+
+
+def t(lang: str, key: str, **kwargs) -> str:
+    lang = lang if lang in SUPPORTED else "am"
+    text = _load(lang).get(key) or _load("en").get(key) or key
+    return text.format(**kwargs) if kwargs else text
+
+
+def all_translations(key: str) -> set[str]:
+    """Same key in every language (used to match localized reply-keyboard buttons)."""
+    return {t(lang, key) for lang in SUPPORTED}

app/core/logging.py

@@ -0,0 +1,10 @@
+import logging
+
+from app.config import get_settings
+
+
+def setup_logging() -> None:
+    logging.basicConfig(
+        level=get_settings().log_level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )

app/db/base.py

@@ -0,0 +1,5 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass

app/db/models/__init__.py

@@ -0,0 +1,7 @@
+from app.db.models.course import Course
+from app.db.models.material import Material
+from app.db.models.pending import PendingMaterial
+from app.db.models.referral import Referral
+from app.db.models.user import User
+
+__all__ = ["User", "Course", "Material", "Referral", "PendingMaterial"]

app/db/models/course.py

@@ -0,0 +1,17 @@
+from typing import Optional
+
+from sqlalchemy import Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Course(Base):
+    __tablename__ = "courses"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    code: Mapped[Optional[str]] = mapped_column(String(32))
+    name: Mapped[str] = mapped_column(String(256))
+    stream: Mapped[Optional[str]] = mapped_column(String(16))
+    year: Mapped[Optional[int]] = mapped_column(Integer)
+    semester: Mapped[Optional[int]] = mapped_column(Integer)

app/db/models/material.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Material(Base):
+    """A file stored as a message in the private library channel (served via copy_message)."""
+
+    __tablename__ = "materials"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    course_id: Mapped[Optional[int]] = mapped_column(ForeignKey("courses.id"))
+    kind: Mapped[str] = mapped_column(String(16), default="slide")  # slide|exam|note|book
+    title: Mapped[str] = mapped_column(String(256))
+    library_chat_id: Mapped[int] = mapped_column(BigInteger)
+    library_message_id: Mapped[int] = mapped_column(BigInteger)
+    file_unique_id: Mapped[Optional[str]] = mapped_column(String(128), unique=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/db/models/pending.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import BigInteger, DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class PendingMaterial(Base):
+    """Filled later by the separate collector userbot; approved by an admin."""
+
+    __tablename__ = "pending_materials"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    source_chat_id: Mapped[Optional[int]] = mapped_column(BigInteger)
+    source_message_id: Mapped[Optional[int]] = mapped_column(BigInteger)
+    file_name: Mapped[Optional[str]] = mapped_column(String(256))
+    caption: Mapped[Optional[str]] = mapped_column(String(1024))
+    file_unique_id: Mapped[Optional[str]] = mapped_column(String(128), unique=True)
+    status: Mapped[str] = mapped_column(String(16), default="pending")  # pending|approved|rejected
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/db/models/referral.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, Integer, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Referral(Base):
+    __tablename__ = "referrals"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    inviter_id: Mapped[int] = mapped_column(BigInteger, index=True)
+    invitee_id: Mapped[int] = mapped_column(BigInteger, unique=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/db/models/user.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import BigInteger, Boolean, DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
+    username: Mapped[Optional[str]] = mapped_column(String(64))
+    full_name: Mapped[str] = mapped_column(String(256), default="")
+    lang: Mapped[str] = mapped_column(String(2), default="am")
+    stream: Mapped[Optional[str]] = mapped_column(String(16))
+    year: Mapped[Optional[int]] = mapped_column(Integer)
+    referred_by: Mapped[Optional[int]] = mapped_column(BigInteger)
+    gate_passed: Mapped[bool] = mapped_column(Boolean, default=False)
+    points: Mapped[int] = mapped_column(Integer, default=0)
+    is_banned: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/db/repos/referrals.py

@@ -0,0 +1,21 @@
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import Referral
+
+
+async def exists_for_invitee(session: AsyncSession, invitee_id: int) -> bool:
+    res = await session.execute(select(Referral.id).where(Referral.invitee_id == invitee_id))
+    return res.scalar_one_or_none() is not None
+
+
+async def add(session: AsyncSession, inviter_id: int, invitee_id: int) -> None:
+    session.add(Referral(inviter_id=inviter_id, invitee_id=invitee_id))
+    await session.flush()
+
+
+async def count_for_inviter(session: AsyncSession, inviter_id: int) -> int:
+    res = await session.execute(
+        select(func.count(Referral.id)).where(Referral.inviter_id == inviter_id)
+    )
+    return int(res.scalar_one())

app/db/repos/users.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import User
+
+
+async def get(session: AsyncSession, user_id: int) -> Optional[User]:
+    return await session.get(User, user_id)
+
+
+async def create(
+    session: AsyncSession,
+    *,
+    user_id: int,
+    username: Optional[str],
+    full_name: str,
+    lang: str,
+    referred_by: Optional[int] = None,
+) -> User:
+    user = User(id=user_id, username=username, full_name=full_name, lang=lang, referred_by=referred_by)
+    session.add(user)
+    await session.flush()
+    return user

app/db/session.py

@@ -0,0 +1,29 @@
+from sqlalchemy.engine import make_url
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import get_settings
+from app.db.base import Base
+
+
+def _build_engine():
+    url = make_url(get_settings().database_url)
+    kwargs: dict = {}
+    connect_args: dict = {}
+    if url.drivername.startswith("postgresql"):
+        # Supabase/Neon: drop ?sslmode=..., force asyncpg, work behind a pooler
+        url = url.set(drivername="postgresql+asyncpg", query={})
+        connect_args = {"ssl": "require", "statement_cache_size": 0}
+        kwargs["poolclass"] = NullPool
+    return create_async_engine(url, connect_args=connect_args, **kwargs)
+
+
+engine = _build_engine()
+SessionFactory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+
+
+async def init_db() -> None:
+    import app.db.models  # noqa: F401  (register tables)
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)

app/main.py

@@ -0,0 +1,34 @@
+import asyncio
+import logging
+
+from aiogram import Bot
+from aiogram.client.default import DefaultBotProperties
+from aiogram.enums import ParseMode
+
+from app.bot.loader import build_dispatcher
+from app.config import get_settings
+from app.core.logging import setup_logging
+from app.db.session import init_db
+
+log = logging.getLogger(__name__)
+
+
+async def run_bot_forever() -> None:
+    setup_logging()
+    await init_db()
+    bot = Bot(
+        token=get_settings().bot_token,
+        default=DefaultBotProperties(parse_mode=ParseMode.HTML),
+    )
+    while True:
+        try:
+            # handle_signals=False because we run in a non-main thread
+            await build_dispatcher().start_polling(bot, handle_signals=False)
+            break
+        except Exception:
+            log.exception("Polling crashed; restarting in 5s")
+            await asyncio.sleep(5)
+
+
+if __name__ == "__main__":
+    asyncio.run(run_bot_forever())

app/services/gate.py

@@ -0,0 +1,34 @@
+"""Channel-membership gate (bot must be an ADMIN of the gate channel to read members)."""
+import logging
+import time
+
+from aiogram import Bot
+from aiogram.enums import ChatMemberStatus
+
+from app.config import get_settings
+
+log = logging.getLogger(__name__)
+_OK = {ChatMemberStatus.CREATOR, ChatMemberStatus.ADMINISTRATOR, ChatMemberStatus.MEMBER}
+_cache: dict[int, float] = {}
+_TTL = 600  # seconds a positive result is trusted
+
+
+async def is_member(bot: Bot, user_id: int, *, fresh: bool = False) -> bool:
+    now = time.time()
+    if not fresh and _cache.get(user_id, 0) > now:
+        return True
+    try:
+        member = await bot.get_chat_member(get_settings().gate_channel, user_id)
+    except Exception as exc:  # fail open: a misconfigured gate must not lock everyone out
+        log.warning("Gate check failed (is the bot admin of the channel?): %s", exc)
+        return True
+    ok = member.status in _OK
+    if ok:
+        _cache[user_id] = now + _TTL
+    else:
+        _cache.pop(user_id, None)
+    return ok
+
+
+def channel_url() -> str:
+    return f"https://t.me/{get_settings().gate_channel.lstrip('@')}"

app/services/referrals.py

@@ -0,0 +1,31 @@
+import logging
+
+from aiogram import Bot
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.i18n import t
+from app.db.models import User
+from app.db.repos import referrals as repo
+from app.db.repos import users as users_repo
+
+log = logging.getLogger(__name__)
+REFERRAL_POINTS = 10
+
+
+async def reward_if_eligible(session: AsyncSession, bot: Bot, invitee: User) -> None:
+    """Called once, when the invitee passes the channel gate (so fake joins don't count)."""
+    if not invitee.referred_by or await repo.exists_for_invitee(session, invitee.id):
+        return
+    inviter = await users_repo.get(session, invitee.referred_by)
+    if not inviter:
+        return
+    await repo.add(session, inviter.id, invitee.id)
+    inviter.points += REFERRAL_POINTS
+    try:
+        await bot.send_message(inviter.id, t(inviter.lang, "referral_reward", points=REFERRAL_POINTS))
+    except Exception as exc:
+        log.info("Could not notify inviter %s: %s", inviter.id, exc)
+
+
+async def stats(session: AsyncSession, user: User) -> tuple[int, int]:
+    return await repo.count_for_inviter(session, user.id), user.points

app/services/users.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+from aiogram.types import User as TgUser
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.db.models import User
+from app.db.repos import users as repo
+
+
+async def get_or_create(
+    session: AsyncSession, tg: TgUser, referrer_hint: Optional[int] = None
+) -> User:
+    user = await repo.get(session, tg.id)
+    if user:
+        return user
+    referred_by = None
+    if referrer_hint and referrer_hint != tg.id and await repo.get(session, referrer_hint):
+        referred_by = referrer_hint
+    return await repo.create(
+        session,
+        user_id=tg.id,
+        username=tg.username,
+        full_name=tg.full_name or "",
+        lang=get_settings().default_lang,
+        referred_by=referred_by,
+    )

locales/am.json

@@ -0,0 +1,23 @@
+{
+  "welcome": "👋 ሰላም <b>{name}</b>!\nወደ <b>DBU Central</b> እንኳን በደህና መጡ።",
+  "gate_text": "ቦቱን ለመጠቀም መጀመሪያ ቻናላችንን ይቀላቀሉ 👇\nከዚያ «✅ ተቀላቅያለሁ» ይጫኑ።",
+  "gate_join_btn": "📢 ቻናሉን ተቀላቀል",
+  "gate_check_btn": "✅ ተቀላቅያለሁ",
+  "gate_not_yet": "ገና ቻናሉን አልተቀላቀሉም። መጀመሪያ ይቀላቀሉ።",
+  "choose_stream": "የትኛው ዘርፍ ላይ ነዎት?",
+  "stream_natural": "🔬 ተፈጥሮ ሳይንስ",
+  "stream_social": "📖 ማህበራዊ ሳይንስ",
+  "choose_year": "የትኛው ዓመት ላይ ነዎት?",
+  "year_label": "{n}ኛ ዓመት",
+  "onboarded": "✅ ተመዝግበዋል! ከታች ካለው ምናሌ ይምረጡ።",
+  "menu_title": "ዋና ምናሌ 👇",
+  "btn_library": "📚 ቤተ-መጻሕፍት",
+  "btn_gpa": "🧮 GPA ማስያ",
+  "btn_invite": "👥 ጓደኛ ጋብዝ",
+  "btn_lang": "🌐 ቋንቋ",
+  "soon": "🚧 ይህ ክፍል በቅርቡ ይመጣል።",
+  "invite_text": "🔗 የእርስዎ መጋበዣ ሊንክ፦\n{link}\n\nየጋበዙት: <b>{count}</b> ሰው\nነጥብ: <b>{points}</b>",
+  "referral_reward": "🎉 አዲስ ጓደኛ በሊንክዎ ተቀላቅሏል! +{points} ነጥብ",
+  "lang_changed": "✅ ቋንቋ ወደ አማርኛ ተቀይሯል።",
+  "banned": "⛔ መለያዎ ታግዷል።"
+}

locales/en.json

@@ -0,0 +1,23 @@
+{
+  "welcome": "👋 Hi <b>{name}</b>!\nWelcome to <b>DBU Central</b>.",
+  "gate_text": "To use the bot, first join our channel 👇\nThen tap «✅ I joined».",
+  "gate_join_btn": "📢 Join channel",
+  "gate_check_btn": "✅ I joined",
+  "gate_not_yet": "You haven't joined the channel yet. Please join first.",
+  "choose_stream": "Which stream are you in?",
+  "stream_natural": "🔬 Natural Science",
+  "stream_social": "📖 Social Science",
+  "choose_year": "Which year are you in?",
+  "year_label": "Year {n}",
+  "onboarded": "✅ You're registered! Pick from the menu below.",
+  "menu_title": "Main menu 👇",
+  "btn_library": "📚 Library",
+  "btn_gpa": "🧮 GPA calculator",
+  "btn_invite": "👥 Invite friends",
+  "btn_lang": "🌐 Language",
+  "soon": "🚧 This section is coming soon.",
+  "invite_text": "🔗 Your invite link:\n{link}\n\nInvited: <b>{count}</b>\nPoints: <b>{points}</b>",
+  "referral_reward": "🎉 A new friend joined with your link! +{points} points",
+  "lang_changed": "✅ Language changed to English.",
+  "banned": "⛔ Your account is banned."
+}

requirements.txt

@@ -0,0 +1,5 @@
+aiogram>=3.13,<4
+sqlalchemy[asyncio]>=2.0
+asyncpg>=0.29
+aiosqlite>=0.20
+pydantic-settings>=2.2

tests/test_i18n.py

@@ -0,0 +1,10 @@
+import json
+from pathlib import Path
+
+LOCALES = Path(__file__).resolve().parents[1] / "locales"
+
+
+def test_same_keys():
+    am = json.loads((LOCALES / "am.json").read_text(encoding="utf-8"))
+    en = json.loads((LOCALES / "en.json").read_text(encoding="utf-8"))
+    assert set(am) == set(en)