natural amharic

app/bot/delivery.py

@@ -0,0 +1,73 @@
+"""Sending things to a student from anywhere (button, deep link, after onboarding)."""
+import logging
+
+from aiogram import Bot
+from aiogram.exceptions import TelegramBadRequest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.bot.keyboards import library as lib_kb
+from app.bot.keyboards.common import share_kb
+from app.core import season
+from app.core.i18n import t
+from app.db.models import Material, User
+from app.db.repos import library as repo
+from app.services import growth
+from app.services import library as lib
+from app.services import xp as xp_service
+
+log = logging.getLogger(__name__)
+
+
+async def _maybe_ask_to_share(bot: Bot, user: User, chat_id: int) -> None:
+    """At the moment a student just got something useful, suggest sharing: at most once a day,
+    never on their first day."""
+    today = season.day_key()
+    if (user.active_days or 0) < 2 or user.share_prompt_day == today:
+        return
+    user.share_prompt_day = today
+    me = await bot.me()
+    link = growth.deep_link(me.username, str(user.id))  # their personal referral link
+    url = growth.share_url(link, t(user.lang, "share_text"))
+    try:
+        await bot.send_message(chat_id, t(user.lang, "share_prompt"), reply_markup=share_kb(user.lang, url))
+    except Exception as exc:
+        log.info("Could not send the share nudge: %r", exc)
+
+
+async def deliver_material(bot: Bot, session: AsyncSession, user: User, material: Material, chat_id: int) -> bool:
+    course = await repo.get_course(session, material.course_id) if material.course_id else None
+    try:
+        await lib.send_material(bot, chat_id, material, course)
+    except TelegramBadRequest:
+        return False
+    material.downloads = (material.downloads or 0) + 1
+    res = await xp_service.award(session, user, "download", 1, ref=f"{material.id}:{season.day_key()}")
+    if res.leveled_up:
+        await xp_service.announce_level(bot, user, res.new_level)
+    await _maybe_ask_to_share(bot, user, chat_id)
+    return True
+
+
+async def deliver_link(bot: Bot, session: AsyncSession, user: User, chat_id: int, kind: str, value: str) -> bool:
+    """Open what a shared link points at (a course or one file). False = nothing to show."""
+    if kind == "course":
+        course, counts = await lib.kinds_of(session, int(value))
+        if course and any(counts.values()):
+            await bot.send_message(
+                chat_id, t(user.lang, "lib_kinds", course=course.name), reply_markup=lib_kb.kinds(user.lang, course.id, counts)
+            )
+            return True
+    elif kind == "file":
+        material = await repo.get_material(session, int(value))
+        if material and material.file_id and material.status == "ok":
+            return await deliver_material(bot, session, user, material, chat_id)
+    return False
+
+
+async def deliver_pending(bot: Bot, session: AsyncSession, user: User, chat_id: int) -> None:
+    """The link someone opened before they had joined / finished onboarding."""
+    if not user.pending_link:
+        return
+    kind, value = growth.parse_start_payload(user.pending_link)
+    user.pending_link = None
+    await deliver_link(bot, session, user, chat_id, kind, value)

app/bot/handlers/__init__.py

@@ -1,6 +1,6 @@
 from aiogram import Router
 
-from app.bot.handlers import admin, gate, inline, library, menu, search, start
+from app.bot.handlers import admin, gate, groups, inline, library, menu, search, start
 
 
 def build_router() -> Router:
@@ -8,6 +8,7 @@ def build_router() -> Router:
     # order matters: specific handlers first, plain-text search fallback LAST
     router.include_router(gate.router)
     router.include_router(admin.router)
+    router.include_router(groups.router)
     router.include_router(start.router)
     router.include_router(menu.router)
     router.include_router(library.router)

app/bot/handlers/admin.py

@@ -2,6 +2,7 @@
 import html
 import logging
 import time
+from datetime import datetime, timedelta, timezone
 from uuid import uuid4
 from typing import Optional
 
@@ -19,6 +20,7 @@ from app.db.repos import library as repo
 from app.db.repos import stats as stats_repo
 from app.core import season as clock
 from app.db.repos import users as users_repo
+from app.services import growth
 from app.services import library as library_service
 from app.services import smart_ingest
 from app.services import watermark as wm
@@ -46,6 +48,8 @@ HELP = (
     "/seedcourses : add the Year-1 course list (safe to run twice)\n"
     "/courses : list courses with ids\n"
     "/delcourse <id> [move_files_to_id] : delete a course (refuses if it still has files)\n"
+    "/growth : where new students come from + a funnel per source\n"
+    "/poster [tag] : printable A4 poster with a QR code (tag = where you will put it, e.g. dorm5)\n"
     "/emptycourses : list courses with no files, with a button to delete them all\n"
     "/gatecheck : is the bot admin in every join-gate channel/group?\n"
     "/stats : numbers\n"
@@ -201,6 +205,38 @@ async def del_course(message: Message, command: CommandObject, session: AsyncSes
     await message.answer(f"🗑 Deleted course #{cid} “{course.name}”{moved}.")
 
 
+@router.message(Command("growth"))
+async def growth_report(message: Message, session: AsyncSession) -> None:
+    since = datetime.now(timezone.utc) - timedelta(days=7)
+    r = await stats_repo.growth_report(session, since)
+    days = "  ".join(f"{d[5:]}: <b>{n}</b>" for d, n in r["by_day"]) or "no new users"
+    lines = [
+        "📈 <b>Growth</b>",
+        f"Total users: <b>{r['total']}</b> · groups using the bot: <b>{r['groups']}</b>",
+        f"New users per day (7 days): {days}",
+        "\n<b>Where they come from</b> (joined → passed gate → onboarded → active 3+ days)",
+    ]
+    for source, joined, gate_ok, onboarded, active in r["by_source"]:
+        lines.append(f"• {source}: {joined} → {gate_ok} → {onboarded} → {active}")
+    lines.append("\nMake a new trackable link by putting a tag after ?start= , e.g. t.me/YourBot?start=dorm5")
+    await message.answer("\n".join(lines))
+
+
+@router.message(Command("poster"))
+async def poster(message: Message, command: CommandObject) -> None:
+    from app.services.poster import make_poster_pdf
+
+    me = await message.bot.me()
+    tag = growth.safe_tag(command.args)
+    link = growth.deep_link(me.username, tag)
+    pdf = make_poster_pdf(link, me.username, get_settings().watermark_link)
+    await message.answer_document(
+        BufferedInputFile(pdf, filename=f"poster-{tag}.pdf"),
+        caption=f"🖨 Print it. The QR opens {link}\nSource tag: <b>{tag}</b>. See who came from it in /growth. "
+        "One poster per place works best: /poster dorm5, /poster cafeteria …",
+    )
+
+
 @router.message(Command("emptycourses"))
 async def empty_courses(message: Message, session: AsyncSession) -> None:
     items = await repo.empty_courses(session)

app/bot/handlers/gate.py

@@ -2,6 +2,7 @@ from aiogram import F, Router
 from aiogram.types import CallbackQuery
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.bot import delivery
 from app.bot.handlers.start import next_step
 from app.core.aio import gather_safe
 from app.core.i18n import t
@@ -23,5 +24,7 @@ async def gate_check(call: CallbackQuery, user: User, session: AsyncSession) ->
         await referral_service.reward_if_eligible(session, call.bot, user)
     if call.message:
         await gather_safe(call.answer(), call.message.delete(), next_step(call.message, user))
+        if user.year is not None:
+            await delivery.deliver_pending(call.bot, session, user, call.from_user.id)
     else:
         await call.answer()

app/bot/handlers/groups.py

@@ -0,0 +1,75 @@
+"""The bot inside class / department groups. Only reacts to being added and to /find:
+no scanning of messages, no unsolicited DMs. Results open in the bot (private), so every new
+student passes the join-gate and onboarding."""
+import logging
+import time
+
+from aiogram import F, Router
+from aiogram.enums import ChatMemberStatus
+from aiogram.filters import Command, CommandObject
+from aiogram.types import ChatMemberUpdated, InlineKeyboardButton, InlineKeyboardMarkup, Message
+
+from app.bot.keyboards.common import open_bot_kb
+from app.bot.keyboards.library import clip, course_icon, course_label
+from app.core.i18n import t
+from app.db.repos import groups as group_repo
+from app.db.session import SessionFactory
+from app.services import growth
+from app.services import library as lib
+from app.services.classifier import display_title
+
+log = logging.getLogger(__name__)
+router = Router()
+GROUP_TYPES = {"group", "supergroup"}
+_last_find: dict[int, float] = {}
+_GONE = (ChatMemberStatus.LEFT, ChatMemberStatus.KICKED)
+_IN = (ChatMemberStatus.MEMBER, ChatMemberStatus.ADMINISTRATOR)
+
+
+@router.my_chat_member()
+async def bot_status_changed(event: ChatMemberUpdated) -> None:
+    chat = event.chat
+    if chat.type not in GROUP_TYPES:
+        return
+    now_in = event.new_chat_member.status in _IN
+    just_joined = now_in and event.old_chat_member.status in _GONE
+    async with SessionFactory() as session:
+        await group_repo.upsert(session, chat.id, chat.title, active=now_in)
+        await session.commit()
+    if just_joined:
+        me = await event.bot.me()
+        try:
+            await event.bot.send_message(
+                chat.id, t("am", "group_welcome"), reply_markup=open_bot_kb(growth.deep_link(me.username, "group"))
+            )
+        except Exception as exc:
+            log.info("Could not greet group %s: %r", chat.id, exc)
+
+
+@router.message(Command("find"), F.chat.type.in_(GROUP_TYPES))
+async def find_in_group(message: Message, command: CommandObject) -> None:
+    now = time.monotonic()
+    if now - _last_find.get(message.chat.id, 0) < 4:  # one answer per chat every 4s: no flooding
+        return
+    _last_find[message.chat.id] = now
+    me = await message.bot.me()
+    open_link = growth.deep_link(me.username, "group")
+    query = (command.args or "").strip()
+    if len(query) < 2:
+        await message.reply(t("am", "group_find_usage"), reply_markup=open_bot_kb(open_link))
+        return
+    async with SessionFactory() as session:
+        courses, materials = await lib.search(session, query, course_limit=4, material_limit=4)
+    if not courses and not materials:
+        await message.reply(t("am", "group_find_none"), reply_markup=open_bot_kb(open_link))
+        return
+    rows = [
+        [InlineKeyboardButton(text=f"{course_icon(c)} {course_label(c)}", url=growth.deep_link(me.username, f"c{c.id}"))]
+        for c in courses
+    ]
+    rows += [
+        [InlineKeyboardButton(text=f"📄 {clip(display_title(m.title))}", url=growth.deep_link(me.username, f"f{m.id}"))]
+        for m in materials
+    ]
+    safe_q = query[:40].replace("<", "").replace(">", "").replace("&", "")
+    await message.reply(t("am", "group_find_result", q=safe_q), reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))

app/bot/handlers/library.py

@@ -6,6 +6,7 @@ from aiogram.exceptions import TelegramBadRequest
 from aiogram.types import CallbackQuery, Message
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.bot import delivery
 from app.bot.keyboards import library as kb
 from app.core import season
 from app.core.aio import gather_results, gather_safe
@@ -18,6 +19,7 @@ from app.services import xp as xp_service
 
 log = logging.getLogger(__name__)
 router = Router()
+router.message.filter(F.chat.type == "private")
 
 
 async def _show(target: Union[Message, CallbackQuery], text: str, markup) -> None:
@@ -99,13 +101,6 @@ async def on_file(call: CallbackQuery, user: User, session: AsyncSession) -> Non
     if not material or not material.file_id or material.status != "ok":
         await call.answer(t(user.lang, "file_missing"), show_alert=True)
         return
-    course = await repo.get_course(session, material.course_id) if material.course_id else None
     await gather_safe(call.answer(), call.bot.send_chat_action(call.from_user.id, "upload_document"))
-    try:
-        await lib.send_material(call.bot, call.from_user.id, material, course)
-        material.downloads = (material.downloads or 0) + 1
-        res = await xp_service.award(session, user, "download", 1, ref=f"{material.id}:{season.day_key()}")
-        if res.leveled_up:
-            await xp_service.announce_level(call.bot, user, res.new_level)
-    except TelegramBadRequest:
+    if not await delivery.deliver_material(call.bot, session, user, material, call.from_user.id):
         await call.message.answer(t(user.lang, "file_missing"))

app/bot/handlers/menu.py

@@ -3,16 +3,18 @@ from aiogram.filters import Command
 from aiogram.types import Message
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.bot.keyboards.common import main_menu
+from app.bot.keyboards.common import main_menu, share_kb
 from app.config import get_settings
 from app.core import season
 from app.core.i18n import all_translations, t
 from app.db.models import User
 from app.db.repos import users as users_repo
+from app.services import growth
 from app.services import referrals as referral_service
 from app.services import xp_rules as R
 
 router = Router()
+router.message.filter(F.chat.type == "private")
 
 
 def _first_name(full_name: str) -> str:
@@ -35,7 +37,11 @@ async def invite(message: Message, user: User, session: AsyncSession) -> None:
     me = await message.bot.me()
     count, qualified = 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, qualified=qualified, points=user.points))
+    share = growth.share_url(link, t(user.lang, "share_text"))
+    await message.answer(
+        t(user.lang, "invite_text", link=link, count=count, qualified=qualified, points=user.points),
+        reply_markup=share_kb(user.lang, share),
+    )
 
 
 @router.message(F.text.in_(all_translations("btn_profile")))

app/bot/handlers/search.py

@@ -8,6 +8,7 @@ from app.db.models import User
 from app.services import library as lib
 
 router = Router()
+router.message.filter(F.chat.type == "private")
 
 
 @router.message(F.text & ~F.text.startswith("/"))

app/bot/handlers/start.py

@@ -3,15 +3,16 @@ from aiogram.filters import CommandObject, CommandStart
 from aiogram.types import CallbackQuery, Message
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.bot.keyboards import library as lib_kb
+from app.bot import delivery
 from app.bot.keyboards.common import main_menu, stream_kb, year_kb
 from app.core.aio import gather_safe
 from app.core.catalog import STREAMS, YEARS
 from app.core.i18n import t
 from app.db.models import User
-from app.services import library as lib
+from app.services import growth
 
 router = Router()
+router.message.filter(F.chat.type == "private")
 
 
 async def next_step(message: Message, user: User, prefix: str = "") -> None:
@@ -28,13 +29,14 @@ async def next_step(message: Message, user: User, prefix: str = "") -> None:
 
 @router.message(CommandStart())
 async def cmd_start(message: Message, command: CommandObject, user: User, session: AsyncSession) -> None:
-    payload = command.args or ""
-    if payload.startswith("c") and payload[1:].isdigit() and user.year is not None:
-        # deep link from inline results: open that course directly
-        course, counts = await lib.kinds_of(session, int(payload[1:]))
-        if course and any(counts.values()):
-            await message.answer(t(user.lang, "lib_kinds", course=course.name), reply_markup=lib_kb.kinds(user.lang, course.id, counts))
-            return
+    payload = (command.args or "").strip()
+    kind, value = growth.parse_start_payload(payload)
+    if kind in ("course", "file"):
+        if user.year is not None:
+            if await delivery.deliver_link(message.bot, session, user, message.chat.id, kind, value):
+                return
+        else:
+            user.pending_link = payload[:16]  # opened as soon as onboarding is done
     welcome = t(user.lang, "welcome", name=message.from_user.full_name)
     await next_step(message, user, prefix=welcome)
 
@@ -58,7 +60,7 @@ async def pick_stream(call: CallbackQuery, user: User) -> None:
 
 
 @router.callback_query(F.data.startswith("ob:year:"))
-async def pick_year(call: CallbackQuery, user: User) -> None:
+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)
@@ -71,5 +73,6 @@ async def pick_year(call: CallbackQuery, user: User) -> None:
             call.message.delete(),
             call.message.answer(t(user.lang, "onboarded"), reply_markup=main_menu(user.lang)),
         )
+        await delivery.deliver_pending(call.bot, session, user, call.from_user.id)
     else:
         await gather_safe(call.answer(), call.message.delete(), next_step(call.message, user))

app/bot/keyboards/common.py

@@ -18,6 +18,15 @@ def gate_kb(lang: str, missing: list[str]) -> InlineKeyboardMarkup:
     return InlineKeyboardMarkup(inline_keyboard=rows)
 
 
+def share_kb(lang: str, url: str) -> InlineKeyboardMarkup:
+    """One tap opens Telegram's own "send to..." picker with a ready message."""
+    return InlineKeyboardMarkup(inline_keyboard=[[InlineKeyboardButton(text=t(lang, "share_btn"), url=url)]])
+
+
+def open_bot_kb(link: str) -> InlineKeyboardMarkup:
+    return InlineKeyboardMarkup(inline_keyboard=[[InlineKeyboardButton(text=t("am", "inline_open_bot"), url=link)]])
+
+
 def stream_kb(lang: str) -> InlineKeyboardMarkup:
     return InlineKeyboardMarkup(
         inline_keyboard=[

app/bot/middlewares/context.py

@@ -5,15 +5,17 @@ from aiogram.types import Message, TelegramObject
 
 from app.core import cache
 from app.db.session import SessionFactory
+from app.services import growth
 from app.services import users as users_service
 from app.services import xp as xp_service
 
 
-def _referrer_from(event: TelegramObject) -> Optional[int]:
+def _payload_of(event: TelegramObject) -> Optional[str]:
+    """The text after /start (referral id, deep link, tracking tag)."""
     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])
+        if len(parts) == 2:
+            return parts[1].strip()
     return None
 
 
@@ -40,6 +42,8 @@ class ContextMiddleware(BaseMiddleware):
         tg = data.get("event_from_user")
         if tg is None or tg.is_bot:
             return await handler(event, data)
+        if isinstance(event, Message) and event.chat.type != "private":
+            return await handler(event, data)  # group chatter: no user record, no gate, no XP
 
         async with cache.lock_for(tg.id):
             snap = cache.get(tg.id)
@@ -48,7 +52,11 @@ class ContextMiddleware(BaseMiddleware):
                     user = users_service.from_snapshot(snap)
                     session.add(user)  # attach without any query
                 else:
-                    user = await users_service.get_or_create(session, tg, _referrer_from(event))
+                    payload = _payload_of(event)
+                    kind, value = growth.parse_start_payload(payload)
+                    user = await users_service.get_or_create(
+                        session, tg, int(value) if kind == "ref" else None, growth.source_label(payload)
+                    )
                 data.update(session=session, user=user, lang=user.lang)
                 if user.is_banned:
                     return None

app/bot/middlewares/gate.py

@@ -6,7 +6,7 @@ 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
+from app.services import gate, growth
 
 
 class GateMiddleware(BaseMiddleware):
@@ -23,6 +23,10 @@ class GateMiddleware(BaseMiddleware):
         if not left:
             return await handler(event, data)
 
+        if is_start:  # keep the link they came with, open it right after they join
+            kind, _ = growth.parse_start_payload((event.text or "").partition(" ")[2])
+            if kind in ("course", "file"):
+                user.pending_link = (event.text or "").partition(" ")[2].strip()[:16]
         lang = user.lang
         text = t(lang, "gate_text") + "\n\n" + t(lang, "gate_missing", list=", ".join(left))
         kb = gate_kb(lang, left)

app/db/migrate.py

@@ -36,6 +36,9 @@ POSTGRES_UPGRADES = [
     "ALTER TABLE materials ADD COLUMN IF NOT EXISTS orig_file_id VARCHAR(512)",
     "ALTER TABLE materials ADD COLUMN IF NOT EXISTS watermarked BOOLEAN NOT NULL DEFAULT FALSE",
     "CREATE INDEX IF NOT EXISTS ix_materials_content_hash ON materials (content_hash)",
+    "ALTER TABLE users ADD COLUMN IF NOT EXISTS source VARCHAR(24)",
+    "ALTER TABLE users ADD COLUMN IF NOT EXISTS pending_link VARCHAR(16)",
+    "ALTER TABLE users ADD COLUMN IF NOT EXISTS share_prompt_day VARCHAR(10)",
     "ALTER TABLE referrals ADD COLUMN IF NOT EXISTS qualified BOOLEAN NOT NULL DEFAULT FALSE",
 ]
 

app/db/models/__init__.py

@@ -1,8 +1,9 @@
 from app.db.models.course import Course
+from app.db.models.group import BotGroup
 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
 from app.db.models.xp import SeasonResult, XpEvent
 
-__all__ = ["User", "Course", "Material", "Referral", "PendingMaterial", "XpEvent", "SeasonResult"]
+__all__ = ["User", "Course", "Material", "Referral", "PendingMaterial", "XpEvent", "SeasonResult", "BotGroup"]

app/db/models/group.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import BigInteger, Boolean, DateTime, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class BotGroup(Base):
+    """A class/department group the bot was added to (every member of it can see the bot)."""
+
+    __tablename__ = "bot_groups"
+
+    chat_id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
+    title: Mapped[Optional[str]] = mapped_column(String(128))
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    added_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/db/models/user.py

@@ -28,5 +28,8 @@ class User(Base):
     day_key: Mapped[Optional[str]] = mapped_column(String(10))
     day_xp: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
     trust: Mapped[int] = mapped_column(Integer, default=100, server_default="100")
+    source: Mapped[Optional[str]] = mapped_column(String(24))  # where they came from (poster, inline, referral...)
+    pending_link: Mapped[Optional[str]] = mapped_column(String(16))  # deep link to open after joining/onboarding
+    share_prompt_day: Mapped[Optional[str]] = mapped_column(String(10))  # last day we suggested sharing
     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/groups.py

@@ -0,0 +1,20 @@
+from typing import Optional
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import BotGroup
+
+
+async def upsert(session: AsyncSession, chat_id: int, title: Optional[str], active: bool) -> None:
+    group = await session.get(BotGroup, chat_id)
+    if group:
+        group.title, group.active = title, active
+    else:
+        session.add(BotGroup(chat_id=chat_id, title=title, active=active))
+    await session.flush()
+
+
+async def count_active(session: AsyncSession) -> int:
+    res = await session.execute(select(func.count()).select_from(BotGroup).where(BotGroup.active.is_(True)))
+    return int(res.scalar_one())

app/db/repos/stats.py

@@ -1,9 +1,11 @@
 from datetime import date
 
-from sqlalchemy import func, select
+from datetime import datetime
+
+from sqlalchemy import case, func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.db.models import Course, Material, Referral, User
+from app.db.models import BotGroup, Course, Material, Referral, User
 
 
 async def _count(session: AsyncSession, stmt) -> int:
@@ -21,3 +23,36 @@ async def overview(session: AsyncSession, today: date) -> dict[str, int]:
         "downloads": await _count(session, select(func.coalesce(func.sum(Material.downloads), 0))),
         "referrals": await _count(session, select(func.count()).select_from(Referral)),
     }
+
+
+async def growth_report(session: AsyncSession, since: datetime) -> dict:
+    """New users per day, and for each source the funnel: joined -> passed gate -> onboarded -> active 3+ days."""
+    day = func.date(User.created_at)
+    by_day = (
+        await session.execute(
+            select(day, func.count()).where(User.created_at >= since).group_by(day).order_by(day)
+        )
+    ).all()
+    source = func.coalesce(User.source, "before tracking")
+    by_source = (
+        await session.execute(
+            select(
+                source,
+                func.count(),
+                func.sum(case((User.gate_passed.is_(True), 1), else_=0)),
+                func.sum(case((User.year.is_not(None), 1), else_=0)),
+                func.sum(case((User.active_days >= 3, 1), else_=0)),
+            )
+            .group_by(source)
+            .order_by(func.count().desc())
+            .limit(12)
+        )
+    ).all()
+    groups = await _count(session, select(func.count()).select_from(BotGroup).where(BotGroup.active.is_(True)))
+    total = await _count(session, select(func.count()).select_from(User))
+    return {
+        "by_day": [(str(d), int(n)) for d, n in by_day],
+        "by_source": [(s, int(n), int(g or 0), int(o or 0), int(a or 0)) for s, n, g, o, a in by_source],
+        "groups": groups,
+        "total": total,
+    }

app/db/repos/users.py

@@ -26,6 +26,7 @@ async def create(
     full_name: str,
     lang: str,
     referred_by: Optional[int] = None,
+    source: Optional[str] = None,
 ) -> User:
     user = User(
         id=user_id,
@@ -33,6 +34,7 @@ async def create(
         full_name=full_name,
         lang=lang,
         referred_by=referred_by,
+        source=source,
         points=0,
         streak=0,
         best_streak=0,

app/services/growth.py

@@ -0,0 +1,42 @@
+"""Organic growth helpers (pure): where did a user come from, links people can share."""
+import re
+import urllib.parse
+from typing import Optional
+
+_TAG = re.compile(r"[A-Za-z0-9_]{1,20}")
+
+
+def parse_start_payload(payload: Optional[str]) -> tuple[str, str]:
+    """/start <payload> -> (kind, value). kind: ref | course | file | tag | none"""
+    p = (payload or "").strip()
+    if not p:
+        return "none", ""
+    if p.isdigit():
+        return "ref", p
+    if re.fullmatch(r"c\d+", p):
+        return "course", p[1:]
+    if re.fullmatch(r"f\d+", p):
+        return "file", p[1:]
+    if _TAG.fullmatch(p):
+        return "tag", p.lower()
+    return "none", ""
+
+
+def source_label(payload: Optional[str]) -> str:
+    """Where the user came from, for the /growth report."""
+    kind, value = parse_start_payload(payload)
+    return {"none": "organic", "ref": "referral", "course": "link", "file": "link"}.get(kind, value)
+
+
+def deep_link(bot_username: str, payload: str) -> str:
+    return f"https://t.me/{bot_username}?start={payload}"
+
+
+def share_url(link: str, text: str) -> str:
+    """Opens Telegram's own 'send to...' picker with a ready message, so sharing is one tap."""
+    return "https://t.me/share/url?" + urllib.parse.urlencode({"url": link, "text": text}, quote_via=urllib.parse.quote)
+
+
+def safe_tag(raw: Optional[str], default: str = "poster") -> str:
+    tag = (raw or "").strip()
+    return tag if _TAG.fullmatch(tag) and not tag.isdigit() else default

app/services/library.py

@@ -84,6 +84,7 @@ async def send_material(bot: Bot, chat_id: int, material: Material, course: Opti
     if course:
         caption += f"\n📚 {course.name}"
     caption += f"\n#{material.kind}"
+    caption += f"\n🤖 @{(await bot.me()).username}"
     kwargs = {material.file_type: material.file_id, "caption": caption}
     sender = {
         "document": bot.send_document,

app/services/poster.py

@@ -0,0 +1,56 @@
+"""A printable A4 poster with a QR code that opens the bot (for dorm walls, class boards, cafeterias).
+Latin text only (standard PDF fonts), so it needs no font files."""
+import io
+
+from reportlab.graphics import renderPDF
+from reportlab.graphics.barcode.qr import QrCodeWidget
+from reportlab.graphics.shapes import Drawing
+from reportlab.lib.pagesizes import A4
+from reportlab.pdfgen import canvas
+
+BLUE = (0.10, 0.30, 0.60)
+
+
+def make_poster_pdf(link: str, bot_username: str, channel_url: str, headline: str = "DBU Freshman Central") -> bytes:
+    w, h = A4
+    buf = io.BytesIO()
+    c = canvas.Canvas(buf, pagesize=A4)
+    c.setTitle(headline)
+
+    c.setFillColorRGB(*BLUE)
+    c.rect(0, h - 190, w, 190, stroke=0, fill=1)  # header band
+    c.setFillColorRGB(1, 1, 1)
+    c.setFont("Helvetica-Bold", 40)
+    c.drawCentredString(w / 2, h - 95, headline)
+    c.setFont("Helvetica", 18)
+    c.drawCentredString(w / 2, h - 135, "Debre Berhan University")
+
+    c.setFillColorRGB(0.1, 0.1, 0.1)
+    c.setFont("Helvetica-Bold", 28)
+    c.drawCentredString(w / 2, h - 255, "Free study materials, one tap away")
+    c.setFont("Helvetica", 20)
+    for i, line in enumerate(("Lecture slides", "Past exams", "Course modules", "Weekly student ranking")):
+        c.drawCentredString(w / 2, h - 300 - i * 28, "-  " + line + "  -")
+
+    qr = QrCodeWidget(link)
+    x0, y0, x1, y1 = qr.getBounds()
+    size = 235
+    drawing = Drawing(size, size, transform=[size / (x1 - x0), 0, 0, size / (y1 - y0), 0, 0])
+    drawing.add(qr)
+    qx, qy = (w - size) / 2, 185
+    c.setFillColorRGB(1, 1, 1)
+    c.setStrokeColorRGB(*BLUE)
+    c.setLineWidth(3)
+    c.roundRect(qx - 16, qy - 16, size + 32, size + 32, 14, stroke=1, fill=1)
+    renderPDF.draw(drawing, c, qx, qy)
+
+    c.setFillColorRGB(*BLUE)
+    c.setFont("Helvetica-Bold", 24)
+    c.drawCentredString(w / 2, 128, "Scan with your phone camera")
+    c.setFont("Helvetica", 18)
+    c.drawCentredString(w / 2, 98, f"or search  @{bot_username}  on Telegram")
+    c.setFont("Helvetica", 14)
+    c.drawCentredString(w / 2, 56, channel_url.replace("https://", ""))
+    c.showPage()
+    c.save()
+    return buf.getvalue()

app/services/users.py

@@ -13,11 +13,12 @@ SNAPSHOT_COLS = (
     "id", "username", "full_name", "lang", "stream", "year", "referred_by",
     "gate_passed", "points", "streak", "best_streak", "last_active_on", "is_banned",
     "active_days", "week_key", "week_xp", "day_key", "day_xp", "trust",
+    "source", "pending_link", "share_prompt_day",
 )
 
 
 async def get_or_create(
-    session: AsyncSession, tg: TgUser, referrer_hint: Optional[int] = None
+    session: AsyncSession, tg: TgUser, referrer_hint: Optional[int] = None, source: Optional[str] = None
 ) -> User:
     user = await repo.get(session, tg.id)
     if user:
@@ -32,6 +33,7 @@ async def get_or_create(
         full_name=tg.full_name or "",
         lang=get_settings().default_lang,
         referred_by=referred_by,
+        source=source,
     )
 
 

locales/am.json

@@ -62,5 +62,12 @@
   "level_10": "ሊቅ",
   "gate_missing": "ገና ያልተቀላቀላችሁት፦ {list}",
   "gate_join_one": "📢 {name} ተቀላቀሉ",
-  "gate_not_yet_list": "ገና አልተቀላቀላችሁም፦ {list}"
+  "gate_not_yet_list": "ገና አልተቀላቀላችሁም፦ {list}",
+  "group_welcome": "👋 ሰላም ክፍል! እኔ የDBU Freshman ቦት ነኝ።\nስላይድ፣ የድሮ ፈተናዎችና ሞጁሎች ላይ ልረዳችሁ ዝግጁ ነኝ 📚\n\nለመፈለግ እንዲህ ጻፉ፦ <code>/find ፊዚክስ</code> 🔍",
+  "group_find_usage": "🔍 ከ /find በኋላ የኮርሱን ስም ጻፉ፣ ለምሳሌ፦ <code>/find physics</code>",
+  "group_find_none": "🔍 ምንም አላገኘሁም። ሌላ ቃል ሞክሩ።",
+  "group_find_result": "🔍 <b>ለ «{q}» ያገኘሁት</b>\nንኩና ቦቱ ውስጥ ክፈቱ 👇",
+  "share_btn": "📤 ለጓደኛ አጋሩ",
+  "share_text": "📚 ለDBU ተማሪዎች ነጻ ማቴሪያሎች፦ ስላይድ፣ የድሮ ፈተናዎች፣ ሞጁሎች — ሁሉም በአንድ ቦታ። እዚህ ጀምሩ 👇",
+  "share_prompt": "👍 ጠቀማችሁ? ለክፍል ጓደኞቻችሁም አጋሩላቸው፤ በሊንካችሁ ሲገቡ XP ታገኛላችሁ 🎁"
 }

locales/en.json

@@ -62,5 +62,12 @@
   "level_10": "Legend",
   "gate_missing": "Still to join: {list}",
   "gate_join_one": "📢 Join {name}",
-  "gate_not_yet_list": "You haven't joined yet: {list}"
+  "gate_not_yet_list": "You haven't joined yet: {list}",
+  "group_welcome": "👋 Hi class! I'm the DBU Freshman bot.\nI have slides, past exams and modules 📚\n\nTo search, type: <code>/find physics</code> 🔍",
+  "group_find_usage": "🔍 Type the course name after /find, e.g. <code>/find physics</code>",
+  "group_find_none": "🔍 Nothing found. Try another word.",
+  "group_find_result": "🔍 <b>Found for «{q}»</b>\nTap to open it in the bot 👇",
+  "share_btn": "📤 Share with a friend",
+  "share_text": "📚 Free study materials for DBU students: slides, past exams, modules, all in one place. Start here 👇",
+  "share_prompt": "👍 Was that useful? Share it with your classmates; you get XP when they join with your link 🎁"
 }

tests/test_logic.py

@@ -361,6 +361,39 @@ def test_locales_stay_in_sync():
         assert sorted(re.findall(r"</?\w+>", am[key])) == sorted(re.findall(r"</?\w+>", en[key])), key
 
 
+def test_growth_payloads_and_links():
+    from app.services import growth as G
+
+    assert G.parse_start_payload(None) == ("none", "")
+    assert G.parse_start_payload("7187749925") == ("ref", "7187749925")
+    assert G.parse_start_payload("c12") == ("course", "12")
+    assert G.parse_start_payload("f40") == ("file", "40")
+    assert G.parse_start_payload("Dorm5") == ("tag", "dorm5")
+    assert G.parse_start_payload("x" * 40) == ("none", "")  # too long / junk is ignored
+    assert [G.source_label(x) for x in (None, "123", "c1", "inline", "poster")] == ["organic", "referral", "link", "inline", "poster"]
+    url = G.share_url("https://t.me/Bot?start=1", "ሰላም & hello")
+    assert url.startswith("https://t.me/share/url?url=https%3A%2F%2Ft.me%2FBot%3Fstart%3D1&text=")
+    assert "%26" in url and " " not in url  # '&' in the text is encoded, no raw spaces
+    assert G.safe_tag("dorm_5") == "dorm_5" and G.safe_tag("123") == "poster" and G.safe_tag("bad tag!") == "poster"
+
+
+def test_poster_is_a_valid_one_page_pdf():
+    try:
+        import io
+
+        from pypdf import PdfReader
+        from reportlab.pdfgen import canvas  # noqa: F401
+    except ImportError:
+        return
+    from app.services.poster import make_poster_pdf
+
+    data = make_poster_pdf("https://t.me/DBUFreshBot?start=poster", "DBUFreshBot", "https://t.me/DBUCentral")
+    reader = PdfReader(io.BytesIO(data))
+    assert len(reader.pages) == 1
+    text = reader.pages[0].extract_text()
+    assert "@DBUFreshBot" in text and "DBU Freshman Central" in text and "t.me/DBUCentral" in text
+
+
 if __name__ == "__main__":
     for name, fn in list(globals().items()):
         if name.startswith("test_"):