Skip to content
GoatWhistlePublic

About

Mentors assemble modules of tasks, invite learners by link and review every submitted solution by hand. Learning group platform with roles, progress tracking and background jobs on FastAPI, PostgreSQL and Celery

Topics

Resources

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

Oriole: groups, modules and tasks, checked automatically

A learning platform where a mentor builds a course out of groups, modules and tasks, and learners get their answers and code checked the moment they submit.

Run locally Running guide API reference

code checks: isolated containers task types: 7
runtimes: Python, JavaScript license: MIT

API: FastAPI and WebSocket storage: PostgreSQL and Redis
jobs: Celery and RabbitMQ web: React 19 and Ant Design
observability: Prometheus, Loki, Grafana

Why it exists How it works Run locally API Structure Limitations

Why it exists

Study groups, clubs and small courses usually live in a chat plus a shared spreadsheet. The mentor posts a task, collects answers by hand, reruns every piece of code on their own machine and keeps scores in a table nobody else can see. Oriole puts that loop in one place: the mentor creates a space, invites people with a link, publishes tasks in order, and the platform grades what it can on its own so the mentor only reviews what needs a human.

How it works

%%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#141317","primaryBorderColor":"#7a3ec9","secondaryColor":"#efedf3","tertiaryColor":"#f7f6f9","lineColor":"#67646d","textColor":"#141317","noteBkgColor":"#efedf3","noteTextColor":"#2f2d35","actorBkg":"#ffffff","actorBorder":"#7a3ec9","fontFamily":"Montserrat"}}}%%
flowchart LR
  M[Mentor] -->|creates| S[Space]
  S --> G[Group]
  G --> Mod[Module]
  Mod --> T[Task]
  L[Learner] -->|joins by link| G
  L -->|submits| Sol[Solution]
  Sol --> API[FastAPI]
  API -->|answer tasks| C1[Instant check]
  API -->|code tasks| Q[RabbitMQ]
  Q --> W[Celery worker]
  W -->|one container per test| R[Python or Node runner]
  R --> V[Verdict]
  C1 --> V
Loading
  • Spaces, groups and modules. A space is the top level: a base space, a group or a course. Groups hold members with roles; modules order the tasks inside a group. People join by invite link or by a request the owner approves.
  • Seven task types. Free answer, string match, multiple choice, file upload, code, AI-assisted and combined tasks share one model, so a module can mix them.
  • Code checks in isolation. A code solution goes to a Celery worker through RabbitMQ. The worker starts a fresh container per test with the task's memory and time limits, compares the output and stores one verdict: accepted, wrong answer, runtime error, time limit or memory limit exceeded.
  • Accounts. Sign-up with email confirmation, password reset, email change and login through Telegram. Tokens are RS256 JWTs with refresh.
  • Group chat. A WebSocket channel per group, with history kept in PostgreSQL. The chat client lives in src/chat/.
  • Limits and caching. Redis backs response caching and a per-client rate limiter.
  • Observability. The API exposes Prometheus metrics; Promtail ships container logs to Loki; Grafana comes up with a provisioned dashboard.

Run locally

You need Docker with Compose and make.

git clone https://github.com/GoatWhistle/oriole.git
cd oriole
cp src/backend/.env.example src/backend/.env
cp src/backend/.env.app_config.example src/backend/.env.app_config
openssl genrsa -out src/backend/jwt-private.pem 2048
openssl rsa -in src/backend/jwt-private.pem -pubout -out src/backend/jwt-public.pem
make up

Fill the ports, database credentials and SMTP account in both .env files before make up. The web app opens at http://localhost, the API at http://localhost:<BACKEND_PORT>. Code tasks need the worker to reach the host Docker socket. Details, service ports and troubleshooting are in docs/running.md.

Command What it does
make up Builds images and starts the stack
make down Stops the stack
make re Rebuilds and restarts
make test Runs backend tests from src/tests

API

All routes live under /api. With IS_DEV=true the backend serves Swagger UI at http://localhost:<BACKEND_PORT>/docs.

Prefix Purpose
/api/auth, /api/auth-via-telegram Login, refresh, Telegram login
/api/users, /api/verify Registration, profile, email confirmation and password reset
/api/spaces, /api/groups Spaces, groups, invites, join requests, roles
/api/modules, /api/tasks Modules, tasks of every type, solutions
/api/chat, /api/websocket Group chat history and live channel
/metrics Prometheus metrics

Structure

src/
  backend/        FastAPI app: features/, core/ (config, Celery, Redis, logging), alembic/
  frontend/       React 19 web app with Ant Design
  chat/           React client for the group chat
  tests/          unit and integration tests
docker/           backend and frontend Dockerfiles, nginx config
monitoring/       Prometheus, Loki, Promtail and Grafana provisioning
docker-compose.yaml

Limitations

  • The code runner supports Python and JavaScript only, and it needs access to the host Docker socket, which gives the worker full control of the Docker daemon. Run it on a machine you trust.
  • AI-assisted and combined task types exist in the data model; automatic grading covers string match, multiple choice and code.
  • The chat client is a separate development app and points at 127.0.0.1:8000.
  • The repository ships no production setup: no TLS, no deployment config, development defaults for RabbitMQ and Grafana credentials.


Team GoatWhistle, 2025. Licensed under MIT.

About

Mentors assemble modules of tasks, invite learners by link and review every submitted solution by hand. Learning group platform with roles, progress tracking and background jobs on FastAPI, PostgreSQL and Celery

Topics

Resources

Stars

6 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages