Technology Stack

Why These Choices

TypeScript over JavaScript

Future RAs may use AI coding assistants (Cursor, GitHub Copilot, Antigravity). Type definitions provide better context for AI code generation and reduce bugs by catching errors at compile time.

Notion as Backend

• No need to learn new database management tools.
• Content updates don't require code changes or redeployments.
• Non-technical team members can manage data directly.
• Backup and version history built-in.
• Lab already has an active Notion Plus subscription.

Server Actions over API Routes

• Simpler code — no need to create separate API endpoints.
• Better performance with fewer network round-trips.
• Type safety between client and server.
• Modern Next.js best practice.

Request Flows

Directory Layout

Key Files to Understand

Prerequisites

• Node.js 18+ installed
• Git installed
• Notion account with access to the Lab4C workspace
• Text editor (VS Code recommended)
• Gmail account with 2-Step Verification enabled

Initial Setup

1. 1
   Clone the repository: git clone [repo-url]
2. 2
   Install dependencies: npm install
3. 3
   Create .env.local — see Environment Variables below.
4. 4
   Run development server: npm run dev
5. 5
   Open http://localhost:3000

Environment Variables

# Notion Integration
NOTION_TOKEN=secret_xxxxxxxxxxxxxxxx
NOTION_MATCHING_DB_ID=xxxxxxxxxxxxxxxx
NOTION_HOME_PAGE_ID=xxxxxxxxxxxxxxxx
NOTION_PROJECTS_DB_ID=xxxxxxxxxxxxxxxx
NOTION_NEWS_DB_ID=xxxxxxxxxxxxxxxx
NOTION_PEOPLE_DB_ID=xxxxxxxxxxxxxxxx

# Gmail SMTP (for verification emails)
GMAIL_USER=your@gmail.com
GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx

Overview

The matching system has four capabilities:

1. Submit information via a custom form
2. Browse and search all entries
3. Receive match suggestions based on shared interests
4. Edit submissions after creation (via email verification)

Domain Autocomplete

Prevents data fragmentation by suggesting existing domains as users type. Instead of separate entries for "HCI", "Human-Computer Interaction", and "human computer interaction", users see existing options and select the standardized version.

Browse Interface

• Responsive grid layout of all entries.
• Real-time search by name or domain.
• Filtering by user type, keywords, and collaboration mode.
• All filtering happens client-side for fast response.
• Domain text limited to 15 lines (clamped). Internal fields like Survey Feedback are hidden from public view.

Match Suggestions

A simple point-based algorithm compares profiles:

• +3 points per shared domain (fuzzy string match)
• +1 point per shared keyword
• +2 points if collaboration mode is compatible

Returns the top 5 matches sorted by score. Prioritizes cross-role matching (Scholars → Practitioners first) by default.

Edit Functionality & Email Verification

Notion Database Schema

Tag Maintenance

The frontend auto-sanitizes tags on submission. For manual cleanup of historical data in Notion:

node scripts/clean-tags.js

This script removes leading # symbols, splits multi-tags like #AIgovernance #AIsafety, and updates Notion automatically.

Static Pages

Home, Lab Prize, and Course pull from a single Notion page and are rendered via the Block Renderer. No database queries — just page content blocks.

Dynamic Sections

Projects, News, and People are Notion Databases. Each entry renders as a card on the frontend, with filtering and sorting handled server-side.

Projects

• Re-Braiding Project — AI-Cybernetics symposium series info
• Cybernetics of Cybernetics — Link to the existing Obsidian vault knowledge graph
• Resources — Papers, definitions, reading lists

How It Works

The website acts as a read-only viewer for most content — static pages, news, people, projects. The exception is the Matching system, where it both reads and writes entries.

Property Type Mapping

Notion has specific JSON formats for each property type. This table maps HTML form inputs to the correct Notion API format:

Workspace Setup

Create a single top-level page called "L4C Website CMS" and place all sub-pages and databases inside it. Share this root page with your Internal Integration — this grants access to everything at once.

Static Pages

People Database

News Database

Full article text goes inside the database page body and is rendered via the Block Renderer.

Environment Variable IDs

After creating each database or page in Notion, copy its ID into your .env.local:

NOTION_HOME_PAGE_ID=your-id-here
NOTION_PRIZE_PAGE_ID=your-id-here
NOTION_COURSE_PAGE_ID=your-id-here
NOTION_PROJECTS_DB_ID=your-id-here
NOTION_PEOPLE_DB_ID=your-id-here
NOTION_NEWS_DB_ID=your-id-here
NOTION_MATCHING_DB_ID=already-set

How It Works

When the site fetches a page from Notion, it receives an array of blocks — paragraphs, headings, dividers, etc. The component receives a single block prop and switches on its type:

switch (block.type) {
  case 'heading_1':
  case 'heading_2':
  case 'heading_3':
    // Uses font-special-condensed + --text-sys-subheading token
    return <HeadingBlock block={block} />;

  case 'paragraph':
    // Parses rich text array: annotations + links
    return <ParagraphBlock block={block} />;

  case 'divider':
    return <hr className="my-[var(--sys-subheading-gap)]" />;
}

Supported Block Types

Heading Number Visual Mapping

Blue Buttons & Project Titles

The renderer repurposes Notion's Heading 3 blocks as stylized blue UI elements — used for "Defining Documents" buttons and Project Titles in news articles.

When the renderer encounters a heading_3 block it checks for a hyperlink (href) in the text:

• With a link — Renders an interactive <a> button with an animated arrow on hover.
• Without a link — Renders a static blue block for project titles. No arrow or hover effects.

Special Intercept Logic

1. Redundant Text Suppression

Certain documents represented by heading_3 buttons have redundant paragraph text that immediately follows them in Notion. The renderer intercepts and suppresses paragraphs starting with specific known phrases.

2. Admin Notes

Any paragraph beginning exactly with the following string is hidden from the public site — allowing maintainers to leave backend notes in Notion:

"NOTE: The window for submissions is open between April 1 and April 30"

Compact Prop

The component accepts an optional compact boolean (default: false) that switches to tighter vertical spacing. Currently used in the site-wide footer (layout.tsx) so multi-line license or attribution text doesn't appear double-spaced.

// Standard spacing (default — used on all content pages)
<BlockRenderer block={block} />

// Compact spacing — used in layout.tsx footer
<BlockRenderer block={block} compact={true} />

Vercel Setup

1. 1
   Connect the GitHub repository to Vercel.
2. 2
   Add all environment variables in the Vercel dashboard (mirror your .env.local).
3. 3
   Vercel auto-deploys on every push to the main branch.

Custom Domain

Currently using: cybernetics.cmu.edu

• DNS records are managed by CMU IT.
• Vercel handles the SSL certificate automatically.

"Notion API Error: Object not found"

• Check that the integration is shared with the specific database or page.
• Verify the database ID is correct in your environment variables.
• Make sure NOTION_TOKEN is valid and hasn't been revoked.

"Email not sending"

• Verify the Gmail App Password is correct (16 characters, spaces allowed).
• Check that 2-Step Verification is still enabled on the Gmail account.
• Gmail may rate-limit — check daily send count.
• Ask the user to check their spam folder.

"Form submission fails"

• Check the browser console for error details.
• Verify all required fields are filled.
• Check that Select / Multi-select options exist in the Notion database.
• Review server logs in the Vercel dashboard.

Content not updating

• Clear Next.js cache: rm -rf .next then restart.
• Check Notion page permissions — confirm the integration still has access.

Autocomplete not working

• Verify the Notion API can query the Matching database.
• Check the domain extraction logic in lib/notion.ts.

For Future Maintainers

Before Making Changes

1. 1
   Read this documentation fully.
2. 2
   Review the PRD (L4C_Website_PRD.md).
3. 3
   Set up your local environment and test it works end-to-end.
4. 4
   Make changes in a feature branch.
5. 5
   Test thoroughly before merging to main.

Contacts

Important Links

Brand Colors

Component Colors

Used exclusively within specific UI components — not general-purpose tokens.

Font Families

Text Scale

Spacing Tokens

Usage in Tailwind v4

<!-- Global page padding -->
<div className="px-[var(--sys-padding)]">

<!-- Max-width content column -->
<div className="max-w-[var(--sys-body-width)] mx-auto">

<!-- Subheading gap for dividers -->
<hr className="my-[var(--sys-subheading-gap)]" />

Blue Action Blocks (heading_3)

Rendered by the Block Renderer when it encounters a heading_3 Notion block. Used for Project Titles and "Defining Document" links.

Dividers (<hr>)

Links