Back to Blog
🇭🇰

SCUHK Alumni Official Website

Published on·4 min read
Portfolio

🏢 Project Overview

The official front-end portal developed for the Soochow University Hong Kong Alumni Association. Built upon Next.js 13 (Pages Router) and utilizing Notion as a Headless CMS, the architecture empowers non-technical administrators to seamlessly manage recent updates, constitutions, school anthems, and member sign-up forms directly inside Notion without altering any source code.

  • Project Type: Jamstack / Headless CMS Official Portal
  • Core Tech Stack: Next.js 13, React 18, Chakra UI, Notion API, Vercel Serverless & Cron

🛑 Challenges & Situation

  1. Notion AWS S3 URL Expiration: Image assets hosted inside Notion databases inherently carry signed parameters expiring after ~1 hour. Relying purely on traditional Build-Time Static Site Generation (SSG) causes widespread broken images as users navigate old static pages.
  2. Granular Notion Block UI Rendering: Notion API dispatches data as deep, fragmented block nodes. Transforming these raw tree nodes into fully-responsive React UI elements—while preserving mixed internal annotations (bold, link, code), list-index nesting, and fluid image renders—required an isolated parsing model.
  3. Automated Tasks in Pure Serverless Infrastructure: Moving completely away from legacy stateful Express backends into Vercel Serverless demanded a headless routine to daily fetch and update Taipei weather and HKD/TWD currency conversion models into the CMS.

🛠️ Technical Actions

1. Resilient Client-Side Image URL Healing Pipeline

  • Asynchronous Asset Verification: Integrated a runtime validation layer inside the useEffect hooks of both ArticleDisplayer and ArticleCard components.
  • On-Demand URL Re-fetching: If an asset fails to fetch or throws a 403/404 error (indicating S3 signature timeout), the client dynamically dispatches a payload to Next.js API Routes (/api/coverFetchAgain or /api/blockImageFetchAgain). The endpoint queries Notion via page_id or block_id, dynamically returning a fresh signed AWS S3 URL to completely eliminate broken layouts.

2. Custom Notion Block Parsing & Rendering Engine

  • High-Fidelity Component Resolver: Authored a standalone layout renderer ArticleDisplayer.jsx to natively parse complex Notion block sets, including structural handling for heading_1/2/3, multi-line paragraph, quote, image, and stateful custom numbered_list_item structures.
  • Rich Annotation Mapping & Custom Injections: Mapped deep text attributes (bold, italic, links, colors) to proper Chakra UI layout tokens. Programmed a unique customize block filter to inject arbitrary React components at specified text intervals dynamically.

3. Hybrid High-Performance Data Flow (SSG + ISR + Serverless Cron)

  • SEO & Speed Maximization: Leveraged Static Site Generation (SSG) via getStaticProps to render blazing fast raw HTML for search engine discoverability, adding an Incremental Static Regeneration (ISR) buffer (revalidate: 10-60) to continuously rebuild files in Vercel's background.
  • Serverless Key-Value Caching Tasks: Implemented a daily Vercel Cron handler at /api/cron triggered automatically at 00:00 UTC (08:00 AM Taiwan time). The function scrapes weather data from the Central Weather Administration and real-time conversion weights from the Bank of Taiwan, storing them inside a Notion WIDGET_DB instance acting as a fast key-value repository.

4. Advanced Schemas, Validation, and Responsive Layout Guards

  • Multi-Tiered Joi Data Cleansing: Embedded Joi 17 schemas inside the client form hooks and the Serverless handler (/api/signup). All incoming registry parameters (Full names, graduation year, faculties) are checked for payload sanitization prior to ingestion into the Notion REG_DB database.
  • Viewport Guardrails: Crafted separate responsive views for desktop (fixed sidebar layout) and mobile (Chakra UI Slide-in panels). Handled landscape mobile constraints inside Layout.jsx by rendering a strict responsive mask to protect layouts against abnormal horizontal aspect distortion.

📈 Results & Impact

  • 100% Code-Free Content Operations: Deployed a fully functional headless environment enabling non-developer staff to easily publish blogs, structural announcements, and organization charts securely.
  • Zero Broken Image Errors: Mitigated the systemic 1-hour AWS S3 access cap enforced by Notion via the dual-track client re-fetching pipeline, maintaining pristine UI layout fidelity.
  • Blazing Fast Metrics & Optimized SEO: Next.js SSG + ISR architecture dropped First Contentful Paint (FCP) significantly. Integrated structured schema data and Open Graph variables via Helmet.jsx, boosting indexing ranks and community sharing presentation.