ristek-verify-backend - Documentation

Document Status
Document Owner	Product Engineering 2026	Product Engineering 2026
Contributors
Project Links	https://github.com/RistekCSUI/ristek-verify-backend	https://github.com/RistekCSUI/ristek-verify-backend
Project Links	https://api.verify.ristek.cs.ui.ac.id	https://api.verify.ristek.cs.ui.ac.id
Project Links	[Monitoring Dashboard]	[Monitoring Dashboard]
Project Links	[API Documentation]	[API Documentation]
Project Links	[Other Related Doc/Link]	[Other Related Doc/Link]
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

This service is a Django-based backend service that manages verifiable RISTEK certificates and prize tickets. The service stores certificate and ticket metadata in PostgreSQL, generates visual artifacts for those records, serves downloadable files from object storage, and exposes verification endpoints that can be consumed by the public verification frontend and internal admin users.

Stakeholders

Users: End users
Upstream Dependencies: PostgreSQL database, S3-compatible object storage bucket for certificate/ticket files, mailer service for outbound emails
Downstream Consumers: Frontend

Scope & Boundaries

In Scope: Django backend in this repository, verify app models, signals, views, templates, and admin, postgreSQL schema for certificate and ticket metadata, file generation and retrieval flow for certificate/ticket assets
Out of Scope: Frontend implementation details outside this repository, historical data migration strategy, monitoring/dashboard implementation, external systems beyond the listed storage, database, and mailer dependencies

⚙️ Architecture & Design

System Diagram

Architecture Decisions (ADRs)

Language/Framework: Python 3.11, Django 4.2.4
Database: PostgreSQL and S3
Communication: Synchronous HTTP for verificatio

💻Technical Specifications

API Documentation

`GET /verify/`

Response 200

{
  "isCert":true,
  "data":{
    "id":"R2026-1234-5678",
    "recipient":"Jane Doe",
    "eventName":"RISTEK Townhall",
    "asWhat":"Speaker",
    "issuedDate":"31/03/2026"
  }
}

Response 200

{
  "isCert":false,
  "data":{
    "id":"R2026-1234-5678",
    "recipient":"Jane Doe",
    "issuedDate":"03.31.2026",
    "expiredDate":"04.30.2026",
    "eventName":"RISTEK Giveaway"
  }
}

`GET /verify/certification/json/`

Response 200

{
  "name":"Jane Doe",
  "eventName":"RISTEK Townhall",
  "asWhat":"Speaker",
  "issuedDate":"31/03/2026"
}

`GET /verify/certification/pdf/`

Response 200

application/pdf

`GET /verify/certification/image/`

Response 200

image/png

`GET /verify/certification/html`

Request

cert_id,name,as_what,event,place,issued_date

Response 200

<html>Rendered certificate template</html>

`GET /verify/ticket/pdf/`

Response 200

application/pdf

`GET /verify/ticket/image/`

Response 200

image/png

`GET /verify/ticket/html///<for_what_occasion>/<due_to>/<event_name>//<issued_date>/<expired_date>`

Response 200

<html>Rendered ticket template</html>

`GET /send-email`

Response 200

success

`GET /admin/`

Response 200

<html>Django admin login or dashboard</html>

Data Model/Schema

Project Structure

ristek-verify-backend/
├── manage.py                      # Django management entrypoint
├── requirements.txt               # Python dependencies
├── Dockerfile                     # Container image definition
├── build_files.sh                 # Build helper for static asset collection
├── scripts/
│   └── docker-entrypoint.sh       # collectstatic + migrate + gunicorn
├── ristek_verify_be/
│   ├── settings.py                # Django settings and infrastructure config
│   ├── urls.py                    # Root URL routing
│   ├── asgi.py
│   └── wsgi.py
├── verify/
│   ├── admin.py                   # Django admin configuration
│   ├── apps.py                    # App registration and signal bootstrapping
│   ├── models.py                  # Certification and Ticket models
│   ├── signals.py                 # File generation, upload, cleanup, email flow
│   ├── storage.py                 # Custom S3 storage URL rewriting
│   ├── urls.py                    # App endpoints
│   ├── views.py                   # Verification and file-serving handlers
│   ├── templates/                 # Certificate and ticket HTML templates
│   ├── static/                    # Images, CSS, and PDF template assets
│   └── migrations/                # Django schema migrations
└── vercel.json                    # Optional Vercel deployment config

Components

Layer	Paths	Responsibility
Core Configuration Layer	`ristek_verify_be/settings.py`, `ristek_verify_be/urls.py`, `ristek_verify_be/asgi.py`, `ristek_verify_be/wsgi.py`	Initializes the Django application shell, including global settings, middleware, database wiring, static file handling, installed apps, root URL routing, and deployment entrypoints for ASGI and WSGI servers.
Verification API Layer	`verify/urls.py`, `verify/views.py`	Handles the public verification flow, including ID lookup across certifications and tickets, certificate metadata retrieval, file download endpoints for certificate and ticket assets, HTML rendering endpoints for certificate and ticket templates, and the debug email endpoint.
Admin Management Layer	`verify/admin.py`	Handles the internal Django admin workflow for Certification and Ticket, including object registration, search configuration, and read-only display of generated IDs and generated file fields after creation.
Domain Model Layer	`verify/models.py`, `verify/utils.py`	Stores and organizes the core business entities Certification and Ticket, including globally unique ID generation, metadata persistence in PostgreSQL, and generated file path assignment for images and PDFs.
Document Generation and Lifecycle Layer	`verify/signals.py`	Handles model lifecycle side effects, including certificate screenshot generation with headless Chrome, PNG-to-PDF conversion, upload to object storage, deletion of stored assets on record removal, and outbound email sending through the configured mailer service.
Storage Integration Layer	`verify/storage.py`	Provides the custom storage abstraction on top of S3-compatible storage, including backend URL rewriting so generated asset links resolve to this service’s verification routes instead of direct bucket objects.
Presentation Template Layer	`verify/templates/cert.html`, `verify/templates/ticket.html`, `verify/static/`	Provides the HTML, CSS, fonts, and image assets used to render the certificate and ticket layouts that are served directly to clients and reused as visual sources in the document generation pipeline.
Runtime Bootstrap Layer	`manage.py`, `scripts/docker-entrypoint.sh`, `Dockerfile`, `build_files.sh`, `requirements.txt`, `vercel.json`	Provides the executable and operational foundation for the backend service, including local Django management commands, dependency installation, static collection, database migration, Gunicorn startup, container image build, and optional Vercel deployment configuration.

☁️ Operational Playbook

Infrastructure

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

Environment Variables

Key	Description	Default (Dev)	Sensitive?
APP_HOST	Host allowed to access the application	*	No
AWS_ACCESS_KEY_ID	AWS access key used to access S3 services	—	Yes
AWS_SECRET_ACCESS_KEY	AWS secret key used for S3 authentication	—	Yes
AWS_S3_REGION_NAME	AWS region where the S3 bucket is hosted	ap-southeast-1	No
AWS_STORAGE_BUCKET_NAME	Name of the S3 bucket used for file storage	ristek-verify	No
DB_HOST	Hostname or IP address of the database server	10.119.107.142	No
DB_PORT	Port used to connect to the database	5432	No
DB_NAME	Name of the database used by the application	ristek_verify	No
DB_USER	Username used to connect to the database	postgres	No
DB_PASS	Password used for database authentication	—	Yes
DEBUG	Flag to enable or disable debug mode	0	No
DJANGO_SECRET_KEY	Secret key used by Django for cryptographic signing	—	Yes
EMAIL_HOST	SMTP server used to send emails	smtp.gmail.com	No
EMAIL_HOST_USER	Email address used for sending emails	rewards@ristek.cs.ui.ac.id	No
EMAIL_HOST_PASSWORD	Password used for the email account	—	Yes
FRONT_END_URL	Base URL of the frontend application	https://verify.ristek.cs.ui.ac.id	No
MAILER_SERVICE_URL	URL of the external mailer service	https://mailer.ristek.cs.ui.ac.id	No
MAILER_TOKEN	Authentication token for mailer service	—	Yes

🙋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 /verify/​

GET /verify/certification/json/​

GET /verify/certification/pdf/​

GET /verify/certification/image/​

GET /verify/certification/html​

GET /verify/ticket/pdf/​

GET /verify/ticket/image/​

GET /verify/ticket/html///&lt;for_what_occasion&gt;/&lt;due_to&gt;/&lt;event_name&gt;//&lt;issued_date&gt;/&lt;expired_date&gt;​

GET /send-email​

GET /admin/​

Data Model/Schema​

Project Structure​

Components​

☁️ Operational Playbook

Infrastructure​

Environment Variables​

🙋Questions

Overview

Stakeholders

Scope & Boundaries

System Diagram

Architecture Decisions (ADRs)

API Documentation

`GET /verify/`

`GET /verify/certification/json/`

`GET /verify/certification/pdf/`

`GET /verify/certification/image/`

`GET /verify/certification/html`

`GET /verify/ticket/pdf/`

`GET /verify/ticket/image/`

`GET /verify/ticket/html///<for_what_occasion>/<due_to>/<event_name>//<issued_date>/<expired_date>`

`GET /send-email`

`GET /admin/`

Data Model/Schema

Project Structure

Components

Infrastructure

Environment Variables