StudentiUniMi backend

What is this?

This is the official repository for the backend code used by StudentiUniMi to operate its website and Telegram groups. The project is mainly written in Python (>=3.11) and uses Django and python-telegram-bot as helper frameworks.

The code is released under MIT license, and the copyright holder is StudentiUniMi.

Features

Website API

Currently, studentiunimi.it uses a series of .json files as the only data source. The goal is to completely replace that unreliable system with a new one supported by a dynamic and more manageable database. Django is the perfect choice because it's easy, and gives a user-friendly admin interface without too many headaches.

We choose to communicate to the frontend with a simple, read-only, JSON, REST API developed with django-rest-framework module. A model is converted to JSON through a serializer as described here and implemented here.

Here's an incomplete list of features:

• University data API

  • Departments
    • List API
    • Verbose details API
    • Representatives
  • Degrees
    • List API
    • Verbose details API
    • Representatives
    • External links
    • Degree general Telegram group
  • Courses
    • List (by degree) API
    • Verbose details API
    • External links
  • External links
  • ...

• ...

Telegram bot

StudentiUniMi has hundreds of Telegram groups, connected with hundreds of courses and dozens of degrees and departments. Currently, it's a mess.

The goal is to create a platform to manage Telegram groups. This includes individual user management, special users (e.g. administrators, professors, representatives, ...), welcome messages and CAPTCHAs, permissions, moderation (global ban, ban, kick, mute, warn, ...), chat statistics, information gathering and automated group creation.

The Bot API has two ways to receive updates: we choose to use webhooks because they can work well with Django. TL;DR: when an event (like a new message) occurs, Telegram will send a POST request to the already specified endpoint with one (or more) Update as content. Django will then process the request with a view (TelegramBotWebhookView) that will dispatch the Update with a telegram.ext.Disptacher.

For security reasons, every authorized bot will have a different endpoint URL ending with its ?token=XXXXX. Before doing any processing, the specified token must match an instance of the TelegramBot model.

Once again, here's an incomplete list of features:

• Architecture

  • Webhook endpoint
  • Ignore request if the bot is not recognized
  • Update dispatcher
  • Translations (i18n)

• Information gathering

  • Users
    • Gather and update general information
    • Update sent message count
    • Update group membership
  • Groups
    • Update, if different, chat title
    • Periodically update chat photo, description, ...

• Groups

  • Welcome messages
    • Greet the user
    • Per-group customized welcome message
    • CAPTCHA and rules acceptance for new users
  • Moderation
    • Auto-ban globally banned users
    • Global ban (temporary and permanent)
    • Group ban (temporary and permanent)
    • Group mute (temporary and permanent)
    • Group kick
    • Global warn
    • Moderation logging
    • Info command for administrators
  • Special users
    • Recognize special users permissions scope
    • Automatically set special user permissions and custom titles
  • Auto-delete welcome and moderation messages
  • Automatic group creation
  • ...

Deployment

We use Docker Swarm to deploy this project on our systems. Tune your settings by editing .env and docker-compose.yml files, then run ./deploy.sh. It's highly recommended using a reverse proxy to run the application in production, like Traefik.

You can use the automatically updated ghcr.io/studentiunimi/backend:latest Docker image if you want the latest version available on the master branch.