susunjadwal-backend - Documentation

Document Status
Document Owner	Product Engineering 2026	Product Engineering 2026
Contributors
Project Links	https://github.com/ristekoss/susunjadwal-backend	https://github.com/ristekoss/susunjadwal-backend
Project Links	https://api-ulaskelas.ristek.cs.ui.ac.id https://api-ulaskelas-stg.ristek.cs.ui.ac.id	https://api-ulaskelas.ristek.cs.ui.ac.id https://api-ulaskelas-stg.ristek.cs.ui.ac.id
Project Links	[Monitoring Dashboard]	[Monitoring Dashboard]
Project Links	[API Documentation]	[API Documentation]
Team	Theodore Kevin Himawan	theodore.kevin@ristek.cs.ui.ac.id
Team	Ari Darrell Muljono	darrell@ristek.cs.ui.ac.id
Team	Grace Karina	gracekarin@ristek.cs.ui.ac.id
Team	Yeshua Marco G. Manurung	marco@ristek.cs.ui.ac.id

🔎 Background

Overview

Susun Jadwal backend provides authentication, course data retrieval, user schedule storage, review submission, and course scraping workflows. The service exists so UI students can sign in with SSO, fetch available courses per major and period, build schedule variants, and request fresh course data when the source data in SIAK changes.

Stakeholders

Users: UI students and admins
Upstream Dependencies: UI CAS/SSO, SIAK academic data sources, RabbitMQ, MongoDB
Downstream Consumers: susunjadwal-frontend

Scope & Boundaries

In Scope: Flask API, MongoDB document models, JWT auth, review moderation, uploader flow, RabbitMQ-based scraping triggers, SSE-based SIAKNG scraping
Out of Scope: frontend implementation, legacy data migration, and analytics pipelines

⚙️ Architecture & Design

System Diagram

Architecture Decisions (ADRs)

Language/Framework: Python, Flask, MongoEngine, Pydantic
Database: MongoDB
Communication: Synchronous HTTP calls

💻Technical Specifications

API Documentation

`GET /`

Response 200

{ "message": "susunjadwal is live!" }

`GET /review`

Response 200

{ "message": "review feature is up" }

`GET /scrape-siak-ng/status`

Response 200

{
  "message": "SIAK NG scraper service is running",
  "version": "1.0"
}

Authentication

`POST /auth/`

Request

{ "ticket": "string", "service_url": "string" }

Response 200

{
  "user_id": "<mongo_id>",
  "major_id": "<mongo_id>",
  "token": "<jwt>",
  "err": false
}

`POST /auth/v2/`

Request

{ "ticket": "string", "service_url": "string" }

Response 200

{
  "user_id": "<mongo_id>",
  "major_id": "<mongo_id>",
  "token": "<jwt>",
  "err": false
}

Response 201

{
  "user_name": "string",
  "full_name": "string",
  "completion_id": "<uuid>"
}

`POST /auth/completion/`

Request

{
  "completion_id": "<uuid>",
  "npm": "string",
  "kd_org": "string"
}

Response 200

{
  "user_id": "<mongo_id>",
  "major_id": "<mongo_id>",
  "token": "<jwt>",
  "err": false
}

`GET /auth/me`

Response 200

{ "message": "token is valid", "token_is_valid": true }

Faculties & Majors

`GET /faculties`

Response 200

["Faculty A", "Faculty B"]

`GET /faculty/<faculty_idx>/majors`

Response 200

{ "kd_org": "Major Name" }

Courses & Periods

`GET /majors/<kd_org>/courses_by_kd`

Response 200

{
  "name": "2025-2",
  "courses": [
    {
      "name": "string",
      "credit": 3,
      "classes": [
        {
          "name": "A",
          "schedule_items": [
            {
              "day": "Mon",
              "start": "08.00",
              "end": "09.40"
            }
          ]
        }
      ]
    }
  ]
}

`GET /majors/<major_id>/all_courses`

Response 200

{
  "courses": [
    {
      "name": "string",
      "code": "string",
      "credit": 3
    }
  ]
}

`GET /courses`

Response 200

{
  "courses": [
    {
      "name": "string",
      "code": "string",
      "credit": 3
    }
  ]
}

User Schedules

`POST /users/<user_id>/user_schedule`

Request

{
  "schedule_items": [
    {
      "name": "Class A",
      "day": "Mon",
      "start": "08.00",
      "end": "09.40"
    }
  ]
}

Response 201

{ "id": "<user_schedule_id>" }

`GET /user_schedules/`

Response 200

{
  "user_schedule": {
    "id": "<id>",
    "name": "Schedule 1",
    "schedule_items": []
  }
}

`GET /users/<user_id>/user_schedules`

Response 200

{
  "user_schedules": [
    {
      "id": "<id>",
      "name": "Schedule 1"
    }
  ]
}

`PUT /users/<user_id>/user_schedules/`

Request

{ "schedule_items": [] }

Response 200

{
  "user_schedule": {
    "id": "<id>",
    "name": "Schedule 1"
  }
}

`POST /users/<user_id>/user_schedules//change_name`

Request

{ "name": "New Name" }

Response 200

{ "id": "<id>", "name": "New Name" }

`DELETE /users/<user_id>/user_schedules/`

Response 204 Scraping

`POST /scrape-schedule`

Request

{ "username": "string", "password": "string" }

`POST /scrape-siak-ng`

Request

{ "username": "string", "password": "string" }

Reviews

`POST /review/<user_id>`

Request

{ "rating": 5, "comment": "Great app" }

Response 201

{ "message": "Review saved" }

Admin

`POST /admin/login`

Request

{ "username": "string", "password": "string" }

Response 200

{ "token": "<admin_jwt>" }

`GET /admin/reviews-overview`

Response 200

{
  "average_rating": 4.5,
  "rating_counts": { "5": 10 }
}

`GET /admin/reviews/list`

Response 200

{
  "reviews": [
    {
      "id": "<id>",
      "rating": 5,
      "comment": "Great"
    }
  ]
}

`PATCH /admin/review/status/`

Request

{ "reviewed": true }

Response 200

{ "id": "<id>", "reviewed": true }

`DELETE /admin/review/delete/`

Response 200

{ "message": "Review deleted successfully." }

Data Model/Schema

Project Structure

susunjadwal-backend/
├── .github/
│   ├── issue-template.md      # issue template for repository contributors
│   └── workflows/
│       ├── deploy-prod.yaml   # production deployment pipeline
│       └── deploy-staging.yaml # staging deployment pipeline
├── .dockerignore              # Docker build ignore rules
├── .env.example               # example environment variable file
├── .gitignore                 # Git ignore rules
├── app/
│   ├── __init__.py            # Flask app setup, config, blueprints, Mongo, CORS, Sentry, RabbitMQ init
│   ├── cron.py                # disabled cron blueprint and scheduled task hooks
│   ├── decorators.py          # JWT and owner/admin authorization decorators
│   ├── exceptions/
│   │   ├── __init__.py
│   │   └── auth.py            # authentication-related custom exceptions
│   ├── jwt_utils.py           # JWT encode/decode helpers
│   ├── message_queue.py       # RabbitMQ connection/pool helpers
│   ├── utils.py               # shared Flask-side utility helpers
│   ├── services/
│   │   ├── __init__.py
│   │   ├── auth/
│   │   │   ├── __init__.py
│   │   │   └── auth.py        # auth v2 and onboarding completion logic
│   │   └── scrapper/
│   │       ├── __init__.py
│   │       └── schedule_scrapper.py # RabbitMQ-backed course refresh orchestration
│   └── views/
│       ├── __init__.py
│       ├── auth.py            # auth and metadata endpoints
│       ├── main.py            # courses and user schedules
│       ├── review.py          # review submission
│       ├── admin.py           # admin review moderation
│       └── scraper.py         # SSE-based SIAK NG scraping
├── models/
│   ├── __init__.py
│   ├── admin.py               # admin credential model
│   ├── major.py               # academic major document
│   ├── period.py              # period, course, class, and schedule embedded schema
│   ├── review.py              # user review document
│   ├── user.py                # user profile and scraping timestamps
│   └── user_schedule.py       # saved user schedule document
├── scraper/
│   ├── __init__.py
│   ├── credentials.template.json # template credential payload for scraper flows
│   ├── main.py                # HTML parsing and uploader ingestion helpers
│   └── siak_ng_scraper.py     # direct SIAK NG scraping and SSE event formatting
├── scripts/
│   ├── init-mongo.sh          # initialize non-root MongoDB user
│   ├── launch.sh              # local Flask launch entrypoint
│   ├── mongo_dump.sh          # MongoDB dump helper
│   └── start.sh               # alternate server startup script
├── sso/
│   ├── __init__.py
│   ├── additional-info.json   # major/faculty metadata lookup
│   ├── cas.py                 # CAS client implementation
│   ├── faculty-base-additional-info.json # faculty base metadata
│   ├── faculty_exchange_route.json # RabbitMQ routing map by faculty
│   └── utils.py               # SSO/CAS helper functions
├── uploader/
│   ├── __init__.py
│   ├── decorators.py          # uploader cookie auth guards
│   ├── templates/
│   │   ├── login.html         # uploader login page
│   │   └── upload.html        # uploader upload form
│   ├── utils.py               # uploader auth and URL helpers
│   └── views.py               # uploader login, logout, and HTML upload endpoints
├── widgets/
│   ├── __init__.py
│   └── flask_pika_mod.py      # Flask-Pika integration wrapper
├── cron.sh                    # cron/container helper script
├── Dockerfile                 # application container build
├── LICENSE.md                 # repository license
├── README.md                  # contributor and setup guide
├── TECH_DOC.md                # technical documentation
├── dev.docker-compose.yaml    # local MongoDB and RabbitMQ stack
├── docker-compose.yaml        # full local container stack
└── requirements.txt           # Python dependency list

Components

Layer	Paths	Responsibility
App Bootstrap	`app/init.py`	Initializes Flask configuration, loads SSO metadata files, registers all blueprints, enables CORS, connects to MongoDB, initializes RabbitMQ, and starts background scraping consumer threads.
Route Layer	`app/views/*.py`, `uploader/views.py`	Exposes HTTP endpoints under /susunjadwal/api, organized by domain including authentication, course catalog, user schedules, reviews, admin moderation, scraping, and uploader workflows.
Auth Services	`app/services/auth/auth.py`, `app/jwt_utils.py`, `app/decorators.py`, `uploader/decorators.py`	Handles CAS-based authentication, JWT generation and validation, onboarding completion flow, role-based access control (user/admin), and uploader cookie authentication.
Domain Models	`models/*.py`	Defines MongoEngine document schemas for admins, users, majors, periods, courses, reviews, and user schedules, including embedded structures for nested data.
Scraping Services for SIAKNG	`app/services/scrapper/schedule_scrapper.py`, `scraper/main.py`, `scraper/siak_ng_scraper.py`	Manages course data scraping via RabbitMQ jobs, parses uploaded HTML files, performs SIAK NG scraping, streams progress using SSE, and stores results into Period documents.
Messaging and Integration	`app/message_queue.py`, `sso/cas.py`, `sso/utils.py`	Provides RabbitMQ connection handling, CAS client implementation, and SSO utility functions used across services.
Review and Admin Workflow	`app/views/review.py`, `app/views/admin.py`, `models/review.py`, `models/admin.py`	Handles user review submission, computes aggregated ratings, supports paginated review listing, and enables admin moderation including status updates and deletion.
Uploader Workflow	`uploader/views.py`, `uploader/utils.py`, `scraper/main.py`	Supports uploader login with whitelist validation, processes HTML uploads, validates period and major, extracts course data, and stores detailed course information for the active period.

☁️ Operational Playbook

Infrastructure

Cloud Provider: Pusilkom
Link: https://api-ulaskelas.ristek.cs.ui.ac.id

Environment Variables

Key	Description	Default (Dev)	Sensitive?
ACTIVE_PERIOD	Active academic period used for filtering courses (e.g. semester identifier)	2025-2	No
ADMIN_CREDENTIAL_VERIFICATION	Method or flag used to verify admin privileges	issuperuser	No
MONGODB_DB	Name of the MongoDB database used by the backend	backend	No
MONGODB_HOST	Hostname or IP address of the MongoDB server	—	Yes
MONGODB_PASSWORD	Password for MongoDB authentication	—	Yes
MONGODB_PORT	Port used to connect to MongoDB	27017	No
MONGODB_USERNAME	Username for MongoDB authentication	—	Yes
RABBITMQ_ERLANG_COOKIE	Shared secret used by RabbitMQ nodes for clustering	—	Yes
RABBIT_HOST	Hostname of the RabbitMQ server	—	Yes
RABBIT_PASSWORD	Password for RabbitMQ authentication	—	Yes
RABBIT_USERNAME	Username for RabbitMQ authentication	—	Yes
SECRET_KEY	Secret key used for JWT signing and application security	—	Yes
SENTRY_DSN	Data Source Name for Sentry error tracking service	—	Yes
SSO_UI_FORCE_HTTPS	Flag to enforce HTTPS in SSO redirects	TRUE	No
UPDATE_COURSE_LIST_EXCHANGE_NAME	Name of RabbitMQ exchange for course list updates	update_course	No

🙋Questions

🗒 List of frequently asked questions or question that need to be answered that is related to this initiative ..

🔎 Background

Overview​

Stakeholders​

Scope & Boundaries​

⚙️ Architecture & Design

System Diagram​

Architecture Decisions (ADRs)​

💻Technical Specifications

API Documentation​

GET /​

GET /review​

GET /scrape-siak-ng/status​

Authentication​

POST /auth/​

POST /auth/v2/​

POST /auth/completion/​

GET /auth/me​

Faculties & Majors​

GET /faculties​

GET /faculty/&lt;faculty_idx&gt;/majors​

Courses & Periods​

GET /majors/&lt;kd_org&gt;/courses_by_kd​

GET /majors/&lt;major_id&gt;/all_courses​

GET /courses​

User Schedules​

POST /users/&lt;user_id&gt;/user_schedule​

GET /user_schedules/​

GET /users/&lt;user_id&gt;/user_schedules​

PUT /users/&lt;user_id&gt;/user_schedules/​

POST /users/&lt;user_id&gt;/user_schedules//change_name​

DELETE /users/&lt;user_id&gt;/user_schedules/​

POST /scrape-schedule​

POST /scrape-siak-ng​

Reviews​

POST /review/&lt;user_id&gt;​

Admin​

POST /admin/login​

GET /admin/reviews-overview​

GET /admin/reviews/list​

PATCH /admin/review/status/​

DELETE /admin/review/delete/​

Data Model/Schema​

Project Structure​

Components​

☁️ Operational Playbook

Infrastructure​

Environment Variables​

🙋Questions

Overview

Stakeholders

Scope & Boundaries

System Diagram

Architecture Decisions (ADRs)

API Documentation

`GET /`

`GET /review`

`GET /scrape-siak-ng/status`

Authentication

`POST /auth/`

`POST /auth/v2/`

`POST /auth/completion/`

`GET /auth/me`

Faculties & Majors

`GET /faculties`

`GET /faculty/<faculty_idx>/majors`

Courses & Periods

`GET /majors/<kd_org>/courses_by_kd`

`GET /majors/<major_id>/all_courses`

`GET /courses`

User Schedules

`POST /users/<user_id>/user_schedule`

`GET /user_schedules/`

`GET /users/<user_id>/user_schedules`

`PUT /users/<user_id>/user_schedules/`

`POST /users/<user_id>/user_schedules//change_name`

`DELETE /users/<user_id>/user_schedules/`

`POST /scrape-schedule`

`POST /scrape-siak-ng`

Reviews

`POST /review/<user_id>`

Admin

`POST /admin/login`

`GET /admin/reviews-overview`

`GET /admin/reviews/list`

`PATCH /admin/review/status/`

`DELETE /admin/review/delete/`

Data Model/Schema

Project Structure

Components

Infrastructure

Environment Variables