Yuqi Guo's Portfolio Platform

A modern Next.js portfolio application for showcasing projects, blogs, CV, visitor analytics, and an AI-powered portfolio assistant. The site is designed as both a personal portfolio and a microservice-backed engineering platform, with serverless frontend APIs, Supabase-backed content storage, Kafka-based event fan-out, OpenSearch search, pgvector RAG indexing, notification delivery, and a real-time visitor analytics pipeline.

Production: https://www.yuqi.site

Maintain this diagram: edit docs/architecture/platform-system-flow.json, then run node scripts/render-architecture-diagram.mjs docs/architecture/platform-system-flow.json.

Connect Claude, Codex, or any Streamable HTTP MCP client to the public endpoint at https://www.yuqi.site/mcp. The connector exposes seven read-only tools for searching portfolio content and retrieving articles, projects, architecture, and professional profile evidence.

Admin MCP requires sign-in with an authorized administrator account. Connect to https://www.yuqi.site/mcp/admin and complete the sign-in and consent flow. Authentication alone does not grant admin access: permissions are enforced by server-managed roles. The public endpoint above remains available without sign-in.

Public MCP · Read-only	Admin MCP · Sign-in required

Read the illustrated MCP connection guide →

The guide covers client setup, the seven public tools, example questions, and the administrator sign-in and consent flow, with screenshots of the interfaces.

In Claude, open Settings → Customize → Connectors, add a custom connector, and use https://www.yuqi.site/mcp as the remote MCP server URL.

Open + → Plugins, select Yuqi Portfolio, and ask Codex to use its tools. For direct MCP setup:

codex mcp add yuqi-portfolio --url https://www.yuqi.site/mcp
codex mcp add yuqi-portfolio-admin --url https://www.yuqi.site/mcp/admin

The admin endpoint remains separately protected by sign-in, server-managed roles, audited execution, and explicit confirmation for write operations.

Application Copilot is a Chrome Manifest V3 extension that runs directly on job application pages. Select Auto-fill Application, review the resolved fields, and apply the approved values. Resume attachment is automatic; final submission remains manual.

Install Application Copilot from the Chrome Web Store →
View source code

• Modern portfolio frontend built with Next.js, including projects, blogs, CV, parallax project detail pages, and guided navigation.
• AI chat assistant with RAG retrieval, multi-round reasoning, intent classification, and MCP tool execution.
• Public MCP integration that gives ChatGPT, Claude, GitHub Copilot, Cursor, and other MCP clients read-only access to projects, articles, stored architecture diagrams, and public profile data.
• Application Copilot that combines an authenticated Chrome extension, MCP workflow, deterministic field resolution, private resume assets, and explicit review before any sensitive field is applied.
• Admin dashboard for managing blogs, projects, life posts, and portfolio content.
• Kafka-driven content pipeline that publishes content change events to search, RAG, and notification consumers.
• Professional search stack using OpenSearch for indexed portfolio search and ranking.
• RAG indexing pipeline using embeddings stored in Supabase PostgreSQL with pgvector.
• Notification system with subscription management, dispatch service, email sender worker, retry handling, and delivery tracking.
• Supabase backend for PostgreSQL, pgvector, storage, RLS policies, and server-side API integration.
• 3D geospatial visitor globe and a real-time /analytics dashboard powered by a Kafka → Spring Boot aggregator pipeline (Valkey dedup, pre-aggregated geo_time_rollups, public visits API).
• SEO support with reusable metadata, robots.txt, and sitemap.xml.

Follow these steps to run the frontend locally.

• Node.js
• npm

Install the latest npm globally if needed:

npm install npm@latest -g

Clone the repository:

git clone https://github.com/YuqiGuo105/Portfolio.git
cd Portfolio

Install dependencies:

npm install

Start the local development server:

npm run dev

Open the application at:

http://localhost:3000

To open the chat widget automatically, append ?openChat=1:

http://localhost:3000/?openChat=1

Copy .env.example to .env.local and fill in your values:

cp .env.example .env.local

See .env.example for all variables with descriptions. For production, configure the same variables in Vercel → Project Settings → Environment Variables.

Score-based bot detection uses Google reCAPTCHA Enterprise and degrades to the existing server-side heuristic when it is not configured or temporarily unavailable:

NEXT_PUBLIC_RECAPTCHA_SITE_KEY=<score-based site key>
RECAPTCHA_PROJECT_ID=<Google Cloud project id>
RECAPTCHA_API_KEY=<server-only restricted API key>
RECAPTCHA_ALLOWED_HOSTS=yuqi.site,www.yuqi.site
RECAPTCHA_TIMEOUT_MS=1500

Restrict the API key to the reCAPTCHA Enterprise API. Never expose RECAPTCHA_API_KEY through a NEXT_PUBLIC_ variable.

1. Create a Supabase project at app.supabase.com.
2. Copy the Project URL and anon public API key from Project Settings → API.
3. Add them to .env as NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY.
4. Copy the service_role key and set it as SUPABASE_SERVICE_ROLE_KEY.
5. Open the Supabase SQL Editor.
6. Run the schema and RLS policy script from create_sql.txt in the repository root.
7. Confirm that required tables, policies, and server-side access patterns are configured correctly.

• Browse projects, blogs, and portfolio details.
• Use the contact form to send messages to the portfolio owner.
• Use the AI chat widget to ask questions about the portfolio.
• Use the Admin Dashboard to edit portfolio content.
• Use Supabase as the source of truth for editable content.
• Use OpenSearch for fast search experiences.
• Use Kafka consumers to keep search, RAG, and notifications in sync.

This project includes basic SEO support:

• Reusable SEO metadata component
• Page-level titles and descriptions
• robots.txt
• sitemap.xml
• Production site URL configuration

Contributions are welcome. To contribute:

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Open a pull request with a clear description of the change.

This project is available under the MIT License.

Copyright (c) 2023-present Yuqi Guo.