PMB 2025 Frontend - Documentation

Document Status
Document Owner	Product Engineering 2026	Product Engineering 2026
Contributors
Project Links	https://github.com/RistekCSUI/pmb2025-frontend	https://github.com/RistekCSUI/pmb2025-frontend
Project Links	https://pmb.cs.ui.ac.id	https://pmb.cs.ui.ac.id
Project Links	https://stg.api.pmb.cs.ui.ac.id (API) / Vercel preview deployments	https://stg.api.pmb.cs.ui.ac.id (API) / Vercel preview deployments
Project Links	Sentry (configured via SENTRY_DSN)	Sentry (configured via SENTRY_DSN)
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

The PMB 2025 Frontend is the student-facing web application for the RISTEK PMB (Penerimaan Mahasiswa Baru) platform. It provides new students with an interactive onboarding experience including SSO-based login, profile setup, friendship/invitation matching (Pansos & Katalink), puzzle games, assignment submissions, event browsing, leaderboards, badges, and QR code interactions — all wrapped in a responsive, mobile-friendly UI.

Stakeholders

• Users: New students (maba), senior mentors, PMB committee (panitia)
• Upstream Dependencies: PMB 2025 Backend API (https://api.pmb.cs.ui.ac.id), UI SSO CAS (https://sso.ui.ac.id/cas2/), AWS S3 (image hosting)
• Downstream Consumers: None (this is the end-user client application)

Scope & Boundaries

• In Scope: User-facing pages (login, onboarding, home, friends, profile, events, assignments, leaderboard, about), SSO authentication flow, Redux state management, API integration with the PMB backend, responsive UI, QR code token system, puzzle game interface.
• Out of Scope: Admin panel (separate project: pmb2025-admin-panel), backend API logic, Data Science recommendation engine, infrastructure provisioning.

⚙️ Architecture & Design

System Diagram

Architecture Decisions (ADRs)

• Language/Framework: TypeScript 4.3.2 / Next.js 12.2.4 (Pages Router) / React 17.0.2
• State Management: Redux Toolkit with redux-persist (localStorage) and async thunks
• Styling: Tailwind CSS 2.1.4 + styled-components 5.3.0 + Chakra UI 1.6.5 + Emotion
• HTTP Client: Axios with JWT interceptor (Authorization: JWT <token>)
• Form Handling: Formik + Yup (validation), react-hook-form (alternative usage)
• Animation: Framer Motion
• Error Monitoring: Sentry (@sentry/nextjs)
• Deployment: Vercel (production on master, staging preview on staging)
• Communication: Synchronous REST calls to PMB Backend API; no SSR data fetching, all API calls happen client-side.

💻Technical Specifications

API Documentation

The frontend communicates with the PMB Backend via an Axios-based service layer in api/services/. All requests include: Authorization: JWT <token> header (from localStorage) Timezone header (from Intl.DateTimeFormat) Base URL resolution (config.ts):

Environment	URL
prod	https://api.pmb.cs.ui.ac.id
dev	https://stg.api.pmb.cs.ui.ac.id
local	http://localhost:5000
Service Modules:
Service	File
---	---
sso	api/services/sso.ts
token	api/services/token.ts
profile	api/services/profile.ts
invitations	api/services/invitations.ts
puzzle	api/services/puzzle.ts
seniors	api/services/seniors.ts
assignment	api/services/assignment.ts
events	api/services/events.ts
katalink	api/services/katalink.ts

Pages & Routes

Route	File	Auth	Description
/	pages/index.tsx	requireAnon	Login page (SSO UI popup / LDAP form)
/terms-and-conditions	pages/terms-and-conditions/index.tsx	requireAuth	Terms & conditions (pre-onboarding)
/onboarding	pages/onboarding.tsx	requireAuth	3-step onboarding: personal info → interests → match
/home	pages/home.tsx	requireAuth	Homepage with events, FAQ, token section
/friends	pages/friends/index.tsx	requireAuth	Friends hub (tabs: Katalink, Puzzle, Seniors/Juniors)
/friends/invitations	pages/friends/invitations/index.tsx	requireAuth	Sent & received invitations list
/friends/invitations/[id]	pages/friends/invitations/[id].tsx	–	Invitation detail
/friends/[id]	pages/friends/[id].tsx	–	Friend profile detail
/friends/seniors/[id]	pages/friends/seniors/[id].tsx	–	Senior profile detail
/friends/invite/[id]	pages/friends/invite/[id].tsx	–	Send invitation flow
/friends/puzzle/[id]	pages/friends/puzzle/[id].tsx	–	Puzzle game interface
/profile	pages/profile/index.tsx	requireAuth	User profile page
/profile/badge	pages/profile/badge/index.tsx	–	Badge collection
/profile/badge/[id]	pages/profile/badge/[id].tsx	–	Badge detail
/assignment	pages/assignment/index.tsx	requireAuth	Assignment list (Maba only)
/assignment/[id]	pages/assignment/[id].tsx	–	Assignment detail with submission
/events	pages/events/index.tsx	requireAuth	Events list (internal/external tabs)
/events/[slug]	pages/events/[slug].tsx	–	Event detail
/leaderboard	pages/leaderboard/index.tsx	–	Leaderboard (individual & group)
/about	pages/about/index.tsx	–	About Fasilkom UI
/failed-qr	pages/failed-qr/index.tsx	–	Failed QR scan handling
/404	pages/404.tsx	–	Custom 404 page

State Management (Redux)

The app uses Redux Toolkit with redux-persist for selective state persistence to localStorage.

Slice	Persisted	Purpose
auth	Yes (token, account)	Authentication state, login/logout, new account flag
profile	No	Profile data, loading states, messages
invitations	No	Sent/received invitation lists
assignment	Yes	Assignment list and details
event	Yes	Event list
seniors	No	Senior list, details, loading states
Services are injected into thunks via extraArgument in the Redux middleware configuration. A custom logger middleware is active in development mode.

Authentication Flow

• SSO UI Login: user clicks login → popup opens backend URL GET /api/auth/login → backend redirects to UI SSO CAS → CAS authenticates → backend renders index.ejs with token → popup sends token to parent via window.postMessage → frontend stores JWT in localStorage.
• LDAP Fallback: username/password form → POST /api/auth/ldap → backend authenticates via RISTEK SSO LDAP or SSO Proxy → returns JWT → frontend stores JWT in localStorage.
• Route Protection: requireAuth HOC checks localStorage for token and redirects to / if missing.
• Onboarding Guard: users without jurusan or User_Interest are redirected through /terms-and-conditions → /onboarding → /home.
• Anonymous Guard: requireAnon HOC redirects logged-in users away from the login page to /home.
• Maba vs Senior: distinguished by comparing angkatan against NEXT_PUBLIC_PMB_YEAR. Maba users have access to assignments; seniors have different friend matching flows.

Data Model/Schema

Core TypeScript interfaces defined in types/:

Type File	Key Interfaces
common.d.ts	ErrorAttribute, ServerError, UserData, ProfileData
seniors.d.ts	Friends
puzzle.d.ts	Friends, PuzzleFriends, MabaReview, Question, QuestionForMaba, Puzzle, PuzzlePayload, PuzzleAnswers, Answer
Additional interfaces are co-located with components (e.g. match.d.ts, invitationInterface.d.ts, friend.d.ts).

Project Structure

pmb2025-frontend/
├── .github/
│   └── workflows/
│       ├── deploy.yml              # Production: push to master → Vercel prod
│       └── staging.yml             # Staging: push/PR to staging → Vercel preview
├── api/
│   └── services/
│       ├── index.ts                # Axios interceptor setup + service aggregation
│       ├── sso.ts                  # SSO/LDAP auth calls
│       ├── token.ts                # Token & QR API calls
│       ├── profile.ts              # Profile, interests, badges, invitations
│       ├── invitations.ts          # Invitation CRUD
│       ├── puzzle.ts               # Puzzle game API
│       ├── seniors.ts              # Senior profiles, messaging
│       ├── assignment.ts           # Assignments & submissions
│       ├── events.ts               # Events & carousel
│       └── katalink.ts             # Friendship recommendations
├── components/
│   ├── common/
│   │   ├── layout.tsx              # Main layout wrapper with Navbar
│   │   ├── requireAuth.tsx         # Auth guard HOC (protected routes)
│   │   ├── requireAnon.tsx         # Anonymous-only HOC (login page)
│   │   └── analytics.ts           # Analytics utilities
│   ├── container/                  # Page-level container components
│   │   ├── Login/                  # SSO popup + LDAP login form
│   │   ├── Onboarding/            # 3-step onboarding flow
│   │   ├── Profile/               # Profile view + edit
│   │   ├── Friends/               # Friends hub with tabs
│   │   ├── Invitations/           # Invitation management
│   │   ├── Events/                # Event listing + detail
│   │   ├── Assignments/           # Assignment listing + submission
│   │   ├── Leaderboard/           # Individual & group rankings
│   │   ├── About/                 # About Fasilkom
│   │   ├── homepage/              # Home page sections
│   │   ├── Footer/                # Page footer
│   │   ├── Loading/               # Loading spinner
│   │   ├── Error/                 # Error display
│   │   ├── TermsConditions/       # T&C page
│   │   ├── FailedQR/              # QR failure handling
│   │   └── FloatingContactButton/ # Contact button overlay
│   ├── module/                    # Shared complex modules
│   │   ├── Navbar/                # Top navigation bar with profile dropdown
│   │   └── DetailsNavbar/         # Back-navigation for detail pages
│   └── elements/                  # Reusable UI primitives
│       ├── Button/, Card/, Form/, Input/
│       ├── Toast/, Popup/, SearchBar/, PageTab/
│       ├── Token/, FriendRequestCard/, Dropzone/
│       ├── InterestBadge/, InfiniteScroll/, Podium/
│       ├── ModalReview/, AdminMessage/
│       └── FloatingContactButton/
├── hooks/
│   ├── windowSize.ts              # useWindowSize hook
│   └── swiperRef.ts              # useSwiperRef hook
├── libs/
│   ├── index.ts                   # Date checks, URL helpers, puzzle utilities
│   ├── dateTime/                  # Date/time formatting helpers
│   ├── Slugify/                   # URL slug generation
│   ├── capitalize/                # String capitalization
│   └── Assignment/                # Assignment-specific utilities
├── pages/
│   ├── _app.tsx                   # App root (Redux Provider, PersistGate, ChakraProvider)
│   ├── _document.tsx              # Custom HTML document
│   ├── _error.tsx                 # Error page with Sentry reporting
│   ├── 404.tsx                    # Custom 404 page
│   ├── index.tsx                  # Login page (root route)
│   ├── onboarding.tsx             # Onboarding page
│   ├── home.tsx                   # Home dashboard
│   ├── friends/                   # Friends routes (index, [id], invitations, puzzle, seniors)
│   ├── profile/                   # Profile routes (index, badge)
│   ├── assignment/                # Assignment routes (index, [id])
│   ├── events/                    # Events routes (index, [slug])
│   ├── leaderboard/               # Leaderboard
│   ├── about/                     # About page
│   ├── terms-and-conditions/      # T&C page
│   └── failed-qr/                 # Failed QR page
├── public/
│   ├── images/                    # Static images and illustrations
│   ├── favicon/                   # Favicon assets
│   └── fonts/                     # Custom fonts (SFProDisplay, Literata, SpaceMono, Oswald)
├── redux/
│   ├── store.ts                   # Redux store config (RTK, persist, thunk with services)
│   ├── reducers.ts                # Root reducer combining all slices
│   ├── middlewares/logger/        # Dev-only logging middleware
│   └── slices/
│       ├── auth/                  # Auth slice (login, logout, token)
│       ├── profile/               # Profile slice
│       ├── invitations/           # Invitations slice
│       ├── assignment/            # Assignment slice
│       ├── seniors/               # Seniors slice
│       └── event/                 # Event slice
├── styles/
│   ├── globals.css                # Global styles (font imports, Swiper overrides)
│   └── Home.module.css            # CSS Module for home page
├── types/
│   ├── common.d.ts                # UserData, ProfileData, errors
│   ├── seniors.d.ts               # Friends type
│   └── puzzle.d.ts                # Puzzle, MabaReview, Question types
├── config.ts                      # API base URL resolution by environment
├── next.config.js                 # Next.js config (image domains, TS/ESLint ignore)
├── tailwind.config.js             # Tailwind config (custom colors, fonts, sizing)
├── postcss.config.js              # PostCSS config
├── tsconfig.json                  # TypeScript config (strict mode, ES5 target)
├── .eslintrc.js                   # ESLint config
├── .prettierrc                    # Prettier config
├── sentry.client.config.js        # Sentry browser initialization
├── sentry.server.config.js        # Sentry server initialization
└── package.json                   # Dependencies and scripts

Components

Layer	Paths	Responsibility
Login	components/container/Login	Provides two auth methods — SSO UI popup (opens backend /api/auth/login in a new window, listens for postMessage with JWT) and LDAP form (username/password POST to backend). Redirects to onboarding or home based on profile completeness.
Onboarding	components/container/Onboarding	Three-step wizard: (1) personal information form (name, birth date, school, social media, domicile), (2) interest selection from predefined categories, (3) friend match preview. Uses Formik + Yup for validation.
Layout	components/common/layout.tsx	Wraps page content with the Navbar component. Navbar is hidden on / (login) and /onboarding. Includes logout popup confirmation.
Friends Hub	components/container/Friends	Tabbed interface with three sections — Katalink (recommendation-based friend matching), Puzzle (puzzle game matching), and Seniors/Juniors (cross-cohort connections). Each tab has its own detail views, invitation flows, and review mechanisms.
Token Section	components/elements/Token	QR code-based friend connection system. Users can generate QR tokens, scan others' codes, and send friend requests via token input.
Assignments	components/container/Assignments	Available only to Maba users. Lists assignments with due dates, supports file upload to S3 via presigned URLs using react-dropzone, and tracks submission status.
Events	components/container/Events	Displays PMB events separated by internal/external tabs, with carousel/banner for featured items. Uses Swiper for carousel slides.
Leaderboard	components/container/Leaderboard	Ranking display with individual and group (kelompok) views, featuring a podium component for top 3 and virtualized scrolling for the full list.
Navbar	components/module/Navbar	Top navigation with profile avatar, dropdown menu (profile, badges, logout), and responsive mobile hamburger menu.

☁️ Operational Playbook

Infrastructure

• Cloud Provider: Vercel
• Production Deployment: Push to master branch → GitHub Actions triggers Vercel production deploy (deploy.yml)
• Staging Deployment: Push/PR to staging branch → GitHub Actions triggers Vercel preview deploy (staging.yml)
• Image CDN: Next.js Image Optimization with allowed domains: images.ctfassets.net, pmb22-staging.s3.ap-southeast-1.amazonaws.com
• Link: https://pmb.cs.ui.ac.id

Environment Variables

(example)

Key	Description	Default (Dev)	Sensitive?
NEXT_PUBLIC_NODE_ENV	Environment selector for API base URL (prod / dev / local)	local	No
NEXT_PUBLIC_PMB_YEAR	Cohort year for Maba vs senior distinction	2025	No
NEXT_PUBLIC_BEGIN_MA	MA (Maba Activity) start date	—	No
NEXT_PUBLIC_BEGIN_MM	MM (Maba Matching) start date	—	No
NEXT_PUBLIC_DEADLINE_MA	MA deadline timestamp	—	No
NEXT_PUBLIC_DEADLINE_MM	MM deadline timestamp	—	No
NEXT_PUBLIC_DEADLINE_MM_SENIOR	Senior MM deadline timestamp	—	No
SENTRY_DSN	Sentry DSN (server-side)	—	Yes
NEXT_PUBLIC_SENTRY_DSN	Sentry DSN (client-side)	—	Yes
WEBDEV_VERCEL_TOKEN	Vercel deploy token (GitHub Actions secret)	—	Yes
ORG_ID	Vercel organization ID (GitHub Actions secret)	—	Yes
PROJECT_ID	Vercel project ID (GitHub Actions secret)	—	Yes

🙋Questions

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