PMB 2025 Frontend - Documentation
🔎 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 rendersindex.ejswith token → popup sends token to parent viawindow.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:
requireAuthHOC checks localStorage for token and redirects to/if missing. - Onboarding Guard: users without
jurusanorUser_Interestare redirected through/terms-and-conditions→/onboarding→/home. - Anonymous Guard:
requireAnonHOC redirects logged-in users away from the login page to/home. - Maba vs Senior: distinguished by comparing
angkatanagainstNEXT_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 ..