Ristek Link Frontend - Documentation

🔎 Background

Overview

The Ristek.Link Frontend is the web application for the RISTEK URL shortening service. It provides a public-facing interface for creating custom short URLs (single and bulk via Excel), generating customizable QR codes, viewing click analytics with charts, and managing user accounts with email/password or Google OAuth authentication. The application also handles short link resolution by rewriting incoming short URLs to the backend redirect API.

Stakeholders

• Users: RISTEK members, general public (anonymous shortening)
• Upstream Dependencies: Ristek.Link Backend API, Google OAuth API, AWS S3 (bulk Excel downloads), Mixpanel (product analytics)
• Downstream Consumers: None (this is the end-user client application)

Scope & Boundaries

• In Scope: URL shortening UI (single and bulk), QR code generation with color/logo customization, click analytics dashboard (visitor, unique visitor, retention charts), user authentication (email/password + Google OAuth), password reset flow, "My URLs" management drawer, short link redirect resolution, maintenance mode, Terms of Service page.
• Out of Scope: Backend API logic, custom subdomain management (superuser-only backend feature), DNS configuration, mobile applications.

⚙️ Architecture & Design

System Diagram

Architecture Decisions (ADRs)

• Language/Framework: JavaScript / Next.js 12.1.6 (Pages Router) / React 18.1.0
• State Management: React Context API (AuthContext, StateManagementContext, DrawerContext, BackdropContext)
• Styling: Tailwind CSS 3.0.24 + Chakra UI 2.0.2 + Emotion + styled-components (enabled via Next.js compiler)
• HTTP Client: Axios for all API calls
• Authentication: JWT stored in httpOnly cookie (UserAuthToken), verified server-side via Next.js API routes
• Charts: Chart.js 4.5.0 + react-chartjs-2
• QR Generation: @cheprasov/qrcode (SVG) + html-to-image (PNG export)
• Icons: Font Awesome (React) + custom SVG icons
• Product Analytics: Mixpanel (browser + server)
• Error Monitoring: Sentry (@sentry/nextjs)
• Ads Integration: @ristek-kit/ads (RISTEK ad platform)
• Deployment: Vercel via GitHub Actions
• Short Link Resolution: Next.js rewrites (/:shortLink* → /api/:shortLink*) handled by a catch-all API route

💻Technical Specifications

API Documentation

The frontend uses Next.js API routes (pages/api/) as a BFF (Backend-for-Frontend) proxy layer. Client-side code calls internal /api/* endpoints, which then forward requests to the Ristek.Link Backend with proper authentication headers. Backend base URL resolution (config/apiTarget.js):

Environment	URL
production	API_URL env var
Other	DEV_API_URL env var

Internal API Routes (pages/api/)

Endpoint	Method	Backend Proxy Target	Description
/api/auth	GET	—	Validate JWT from UserAuthToken cookie, return token or status
/api/auth	POST	POST /auth/login	Email/password login, sets httpOnly cookie
/api/google	POST	POST /auth/google	Google OAuth login, sets httpOnly cookie
/api/logout	POST	—	Clears UserAuthToken cookie
/api/register	POST	POST /auth/register	User registration
/api/resetPassword	POST	POST /auth/reset-password	Reset password with token
/api/shorten	POST	POST /shorten	Create short URL
/api/shorten	PUT	PUT /shorten	Edit existing short URL (auth required)
/api/urls	GET	GET /shorten	List user's URLs (auth required)
/api/analytic	GET	GET /analytics	Get analytics for a short URL (auth required)
/api/generateQR	PATCH	PATCH /shorten/generate-qr	Generate custom QR code
/api/bulkShortener	POST	POST /shorten/bulk	Bulk URL shortening from Excel
/api/[...shortLink]	GET	POST /shorten/redirect	Resolve short link → redirect to target URL
Direct backend call (not proxied):

POST /auth/forgot-password

Called directly from pages/login/forgot.js.

Pages & Routes

Route	File	Auth Required	Description
/	pages/index.js	No	Landing page with URL shortener, QR generator, analytics (state-driven)
/login	pages/login/index.js	No	Login (email/password + Google OAuth)
/login/forgot	pages/login/forgot.js	No	Forgot password (sends reset email)
/login/reset	pages/login/reset.js	No	Reset password (with JWT token from email)
/register	pages/register/index.js	No	User registration
/bulk-shortener	pages/bulk-shortener/index.js	No	Bulk URL shortening with Excel upload
/terms-of-service	pages/terms-of-service.js	No	Terms of Service (13 content sections)
/maintenance	pages/maintenance.js	No	Maintenance mode page (shown when MAINTENANCE_MODE=true)
/404	pages/404.js	No	Custom 404 page
/:shortLink*	Rewrite → /api/[...shortLink]	No	Short link resolution and redirect

State Management (React Context)

Context	File	State	Purpose
AuthContext	context/AuthContext/AuthContext.js	user, loggingIn, authStatus	Authentication state, login/logout/authenticate functions
StateManagementContext	context/StateManagementContext/StateManagementContext.js	state, dataLink, analyticState, rangeState, file, bulkShortenerState, processing	Landing page view state (shortener/QR/analytics), active link data, chart range
DrawerContext	context/DrawerContext/DrawerContext.js	drawerOpened, urls, loadingUrls, featureDrawerOpened	"My URLs" side drawer state, URL list, refresh function
BackdropContext	context/BackdropContext/BackdropContext.js	backdropActive	Overlay backdrop visibility
Auth status enum:
AUTHENTICATED (1) — valid JWT in cookie
NOT_AUTHENTICATED (2) — no token, no prior session
SESSION_EXPIRED (3) — had token but it's gone (shows toast)
TOKEN_UNVERIFIED (4) — token exists but failed verification (shows toast)

Authentication Flow

• Email/Password Login: form submit → POST /api/auth → API route proxies to backend POST /auth/login → sets UserAuthToken as an httpOnly, sameSite strict cookie → AuthContext.login() stores the user in state and localStorage.
• Google OAuth Login: @react-oauth/google provides token → POST /api/google → API route proxies to backend POST /auth/google → uses the same cookie flow.
• Session Validation: on page load, AuthContext.authenticate() calls GET /api/auth → API route reads UserAuthToken cookie → verifies JWT with jsonwebtoken using JWT_SECRET → returns token or status code (TOKEN_UNVERIFIED, TOKEN_DOES_NOT_EXIST).
• Logout: POST /api/logout → clears cookie → clears localStorage while preserving hasOpen and lastBulk.
• Short Link Device Tracking: DeviceId cookie (UUID) is set on first short-link redirect for unique click analytics.

Short Link Resolution

Short URLs (e.g. ristek.link/my-link) are resolved via:

• Rewrite: /:shortLink* → /api/:shortLink*
• Resolver: pages/api/[...shortLink].js calls backend POST /shorten/redirect with the short code and DeviceId cookie.
• Success: 302 redirect to the target URL.
• Failure: redirect to the Ristek Link homepage.

Project Structure

ristek.link-frontend/
├── .github/
│   └── workflows/
│       ├── deploy.yml                  # Production: push to main → Vercel prod
│       └── preview.yml                 # Staging: push to staging → Vercel preview
├── components/
│   ├── common/
│   │   ├── Backdrop/Backdrop.js        # Overlay backdrop component
│   │   ├── Banner/                     # Announcement banners
│   │   │   ├── Banner.js               # Banner UI
│   │   │   └── BannerContainer.js      # Banner state management
│   │   ├── Button/index.js             # Reusable button component
│   │   ├── FeatureDrawer/              # Mobile drawer for QR/Analytics
│   │   │   ├── FeatureDrawer.js        # Drawer container
│   │   │   └── components/             # Drawer sub-components
│   │   ├── Icon/                       # CopyIcon, PngDownloadIcon, WarningIcon, etc.
│   │   ├── Input/Input.js              # Reusable input component
│   │   └── URLDrawer/                  # "My URLs" side drawer
│   │       ├── URLDrawer.js            # Drawer container with URL list
│   │       ├── URLCard.js              # Single URL card (copy, edit, QR, analytics)
│   │       ├── OpenDrawerlogo.js       # Drawer toggle button
│   │       ├── Logos.js                # Drawer logo assets
│   │       └── components/             # URLDrawerComponents/ sub-components
│   ├── layout/
│   │   ├── Layout.js                   # Page wrapper (Navbar, Footer, Backdrop, FeatureDrawer)
│   │   ├── Footer/
│   │   │   ├── Footer.js               # Site footer
│   │   │   └── SocialContainer.js      # Social media links
│   │   └── Navbar/
│   │       ├── Navbar.js               # Top nav with auth state, login/logout
│   │       └── components/             # Navbar sub-components
│   ├── pages/
│   │   ├── Analytic/                   # Click analytics view
│   │   │   ├── Analytic.js             # Main analytics component with Chart.js
│   │   │   └── components/             # Chart, stats sub-components
│   │   ├── AuthPage/                   # Login/register form components
│   │   │   ├── FormHeader.js           # Auth form header
│   │   │   ├── FormFields.js           # Auth form fields
│   │   │   └── components/             # Google button, form sub-components
│   │   ├── BulkShortener/              # Bulk URL shortening
│   │   │   ├── BulkShortener.js        # Multi-step bulk flow with Excel upload
│   │   │   └── component/              # Upload, progress, result sub-components
│   │   ├── GenerateQR/                 # QR code generation
│   │   │   ├── GenerateQR.js           # QR generation with color picker
│   │   │   ├── Preview.js              # QR preview
│   │   │   ├── QROption.js             # QR customization options
│   │   │   └── ...                     # Download, option sub-components
│   │   ├── Landing/                    # Main landing page
│   │   │   ├── Landing.js              # State-driven view (shortener/QR/analytics)
│   │   │   ├── Container.js            # Page container
│   │   │   ├── ShortenerInput.js       # Landing shortener input
│   │   │   └── ...                     # Success modal, input sub-components
│   │   ├── TermsOfService/             # Terms of Service
│   │   │   ├── TermsOfService.js       # ToS wrapper
│   │   │   └── (13 section components) # Individual ToS sections
│   │   └── URLShotener/                # URL shortener feature
│   │       ├── URLShortener.js         # Shortener container
│   │       ├── ShortenerInput.js       # Form logic, validation, API call
│   │       └── Logo.js                 # Shortener branding
│   └── utils/
│       ├── useCustomToast.js           # Chakra useToast wrapper
│       ├── chart.js                    # Chart.js registration (scales, elements)
│       └── downloadFromS3.js           # Download Excel results from S3
├── config/
│   ├── apiTarget.js                    # Backend API URL resolver (prod/dev)
│   └── awsConfig.js                    # AWS S3 config (bucket, keys)
├── context/
│   ├── AuthContext/AuthContext.js       # Auth state, login/logout/authenticate
│   ├── StateManagementContext/StateManagementContext.js # Landing page view state
│   ├── DrawerContext/DrawerContext.js   # URL drawer state
│   └── BackdropContext/BackdropContext.js # Backdrop overlay state
├── hooks/
│   ├── useWindowSize.js                # Window dimension hook
│   ├── useMixpanelClient.js            # Mixpanel client-side tracking
│   └── useMixpanelServer.js            # Mixpanel server-side tracking
├── pages/
│   ├── _app.js                         # App root (providers: Auth, Google OAuth, Chakra, Contexts, Ads, Layout)
│   ├── _error.js                       # Error page with Sentry
│   ├── 404.js                          # Custom 404
│   ├── index.js                        # Landing page
│   ├── maintenance.js                  # Maintenance mode page
│   ├── terms-of-service.js             # Terms of Service page
│   ├── bulk-shortener/index.js         # Bulk shortener page
│   ├── login/
│   │   ├── index.js                    # Login page
│   │   ├── forgot.js                   # Forgot password
│   │   └── reset.js                    # Reset password
│   ├── register/index.js               # Registration page
│   └── api/                            # Next.js API routes (BFF proxy)
│       ├── auth.js                     # Auth validation + login proxy
│       ├── google.js                   # Google OAuth proxy
│       ├── logout.js                   # Cookie clear
│       ├── register.js                 # Registration proxy
│       ├── resetPassword.js            # Password reset proxy
│       ├── shorten.js                  # Create/edit short URL proxy
│       ├── urls.js                     # List user URLs proxy
│       ├── analytic.js                 # Analytics proxy
│       ├── generateQR.js              # QR generation proxy
│       ├── bulkShortener.js            # Bulk shorten proxy
│       └── [...shortLink].js           # Catch-all short link redirect
├── public/
│   ├── images/                         # SVG assets (logos, icons, illustrations)
│   └── vercel.svg
├── styles/
│   ├── globals.css                     # Global styles (Poppins font, base resets)
│   └── theme.js                        # Chakra UI custom theme
├── next.config.js                      # Next.js config (Sentry, env vars, rewrites, headers)
├── tailwind.config.js                  # Tailwind config (custom colors, animations, JIT)
├── postcss.config.js                   # PostCSS (Tailwind + autoprefixer)
├── sentry.client.config.js             # Sentry client initialization
├── sentry.server.config.js             # Sentry server initialization
├── sentry.properties                   # Sentry org/project config
├── .eslintrc.json                      # ESLint (next/core-web-vitals)
├── .env.example                        # Environment variable template
└── package.json                        # Dependencies and scripts

Components

Layer	Paths	Responsibility
Landing Page	components/pages/Landing/Landing.js	The main view at /, driven by StateManagementContext.state. Switches between three sub-views: URL Shortener (default), QR Code Generator, and Analytics. Includes a success modal after shortening and integrates with the URL drawer for authenticated users.
URL Shortener	components/pages/URLShotener/	Two-input form (long URL + custom alias). Validates URL format, checks for duplicate aliases, and calls POST /api/shorten. Supports both anonymous and authenticated shortening. Displays the resulting short link with copy-to-clipboard functionality.
Bulk Shortener	components/pages/BulkShortener/BulkShortener.js	Multi-step flow: (1) Excel file upload with template download, (2) processing indicator, (3) results summary (success/fail counts) with downloadable result Excel from S3. Max 100 links per batch.
QR Code Generator	components/pages/GenerateQR/	Customizable QR code generation for existing short URLs. Features a color picker (react-colorful), optional RISTEK logo toggle, SVG preview, and PNG/SVG download via html-to-image and downloadjs.
Analytics Dashboard	components/pages/Analytic/	Bar chart visualization using Chart.js showing visitor and unique visitor data. Supports three time ranges (week, month, six months) with pagination. Displays aggregate stats (total, average, max, min, percentage change).
URL Drawer	components/common/URLDrawer/	Slide-in side panel showing authenticated user's URLs. Each URL card displays click counts, creation date, and provides actions: copy link, edit URL/alias, generate QR, view analytics. Includes search filtering.
Feature Drawer	components/common/FeatureDrawer/	Mobile-optimized bottom drawer for accessing QR generation and analytics features on smaller screens.
Layout	components/layout/Layout.js	Page wrapper providing Navbar, Footer, Backdrop overlay, and the Feature/URL drawers. Applied globally via _app.js.
Navbar	components/layout/Navbar/Navbar.js	Top navigation with RISTEK logo, navigation links (Bulk Shortener, Terms of Service), and auth-aware UI (Login/Register buttons or user dropdown with logout).
App Root	pages/_app.js	Provider hierarchy: AuthContextProvider → GoogleOAuthProvider → ChakraProvider → StateManagementContextProvider → BackdropContextProvider → DrawerContextProvider → AdsProvider → Layout. Shows maintenance page when MAINTENANCE_MODE=true.

☁️ Operational Playbook

Infrastructure

• Cloud Provider: Vercel
• Production Deployment: Push to main branch → GitHub Actions (deploy.yml) → Vercel production deploy
• Staging Deployment: Push to staging branch → GitHub Actions (preview.yml) → Vercel preview deploy
• Link: https://ristek.link

Environment Variables

(example)

Key	Description	Default (Dev)	Sensitive?
API_URL	Backend API URL (production)	—	No
DEV_API_URL	Backend API URL (development)	—	No
NODE_ENV_TARGET	Environment selector (production / other)	—	No
JWT_SECRET	JWT verification secret (must match backend)	—	Yes
GOOGLE_CLIENT_ID	Google OAuth Client ID	—	Yes
SENTRY_DSN	Sentry DSN for error tracking	—	Yes
SENTRY_AUTH_TOKEN	Sentry auth token for source maps	—	Yes
NEXT_PUBLIC_AWS_BUCKET_NAME	S3 bucket for bulk Excel downloads	—	No
NEXT_PUBLIC_AWS_ACCESS_KEY_ID	AWS access key ID (client-side)	—	Yes
NEXT_PUBLIC_AWS_ACCESS_KEY_VALUE	AWS secret key (client-side)	—	Yes
NEXT_PUBLIC_MIXPANEL_PROJECT_TOKEN	Mixpanel project token for product analytics	—	No
MAINTENANCE_MODE	Enable maintenance page ("true" / "false")	"false"	No
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 ..