Tay Za
Back to Garden

Premium Founder Portfolio Documentation

2026-05-30
documentationarchitecturerag

Tay Za - Premium Founder Portfolio Documentation

Welcome to the official developer documentation for the Premium Founder Portfolio web application. This document serves as a comprehensive guide to the codebase architecture, visual design system, interaction patterns, and the custom Retrieval-Augmented Generation (RAG) AI Chat integration.

📖 Table of Contents

  1. System Overview & Core Philosophy
  2. Codebase Directory Structure
  3. Architecture Map & Key Modules
  4. Design System & High-Fidelity UI Components
  5. Interactive AI Twin & RAG Engine
  6. Embedding Precomputation Pipeline
  7. Environment Configuration & Local Setup
  8. Production Build & Deployment Guidelines

1. System Overview & Core Philosophy

Rather than presenting a traditional, static, text-heavy résumé, this portfolio is engineered as a dynamic, highly interactive single-page SaaS dashboard. It positions the owner, Tay Za, as a results-driven systems architect and startup founder actively developing software infrastructure within the Myanmar and Thailand markets.

Key Conceptual Columns

  • Proof of Work over Promise: Live active indicators, automated metrics, and architectural breakdowns.
  • Immersive User Interaction: Organic physical physics (spring-based parallax movement, magnetic pulls, mouse spotlight glows).
  • AI-Native Engagement: A dedicated in-character "AI twin" chatbot powered by Gemini, capable of retrieving knowledge on demand through local semantic vector comparison (RAG).

2. Codebase Directory Structure

Portfolio/
├── .env.example                    # Template for required API keys
├── eslint.config.mjs               # ESLint code style rules
├── next.config.ts                  # Next.js configuration
├── package.json                    # Dependencies & npm build scripts
├── postcss.config.mjs              # PostCSS & Tailwind V4 compiler hook
├── tsconfig.json                   # TypeScript configuration
│
├── public/                         # Public assets (images, favicon, etc.)
│   └── hero-background.png        # Underlay image for the parallax hero block
│
├── scripts/
│   └── generate-embeddings.mjs     # CLI pipeline to precompute vectors via Gemini API
│
└── src/
    ├── app/
    │   ├── api/chat/
    │   │   └── route.ts            # Secure serverless RAG API endpoint (POST)
    │   ├── favicon.ico
    │   ├── globals.css             # Base styles, variables, & utility classes
    │   ├── layout.tsx              # Root HTML wrapper, provider, & ambient glows
    │   └── page.tsx                # Single-page layout section assembler
    │
    ├── components/
    │   ├── chat/
    │   │   └── AiChat.tsx          # Chat interface, suggest chips, & markdown typewriter
    │   ├── layout/
    │   │   ├── Footer.tsx          # Sleek modern footer with social connections
    │   │   └── Navbar.tsx          # Dynamic header scroll tracking & link highlights
    │   ├── sections/
    │   │   ├── Dashboard.tsx       # Live counters & status indicators
    │   │   ├── Hero.tsx            # Parallax banner with magnetic CTAs
    │   │   ├── Projects.tsx        # Systems architecture problem/solution layouts
    │   │   ├── Roadmap.tsx         # Future trajectory timeline & booking options
    │   │   └── Vision.tsx          # Strategic market thesis & Operating System grid
    │   └── ui/
    │       ├── AnimatedSection.tsx # Staggered framer-motion scroll wrappers
    │       ├── Button.tsx          # Magnetic interactive buttons
    │       ├── Counter.tsx         # Scroll-triggered statistical counters
    │       ├── GlassCard.tsx       # Cursor spotlighting & 3D tilt glass container
    │       ├── MagneticButton.tsx  # Wrapper for custom magnetic pulling force
    │       ├── NoiseOverlay.tsx    # Low-opacity fractal background noise texture
    │       └── ScrollProgress.tsx  # Sleek top screen-linked progress line
    │
    ├── data/
    │   ├── portfolio-embeddings.json # Precomputed knowledge vector database
    │   └── portfolio-knowledge.json  # Raw markdown chunks for the AI's memory
    │
    └── lib/
        └── utils.ts                # Tailwind Classname merger (clsx + tailwind-merge)

3. Architecture Map & Key Modules

The application is built on Next.js 16 (App Router), React 19, and written in TypeScript.

Root Entry Points

  • src/app/layout.tsx: Handles global typography imports (Outfit for heading/body copy and Geist_Mono for statistics/source references), sets SEO meta details, defines background ambient violet/indigo radial gradients, and mounts background enhancements (NoiseOverlay, ScrollProgress).
  • src/app/page.tsx: Stitches together the single-page layout hierarchy with responsive gradient dividers (h-px max-w-5xl mx-auto bg-gradient-to-r).

Visual Sections

  • Hero.tsx: Sets the theme of a premium builder. Houses mouse coordinate tracking translating into multi-layered spring-smoothed parallax underlays, and calls magnetic action controls.
  • Dashboard.tsx & TelemetryDashboard.tsx: Shows operational columns (MyanTop Top-up, WebSocket Algorithmic Trading, SecureXchange Escrow) alongside live engineering telemetry (Activity Pulse Graph, Contribution Heatmap, Tech Stack Radar). When they enter the viewport, the numbers dynamically count up using physical easing and visualizations render smoothly.
  • Projects.tsx: Segregates showcase cards by Category, Stack, Metrics, Problems, and Solutions. Links out to GitHub.
  • Vision.tsx: Details market dynamics (Fintech automation potential in Myanmar vs Crypto/SaaS maturity in Thailand), and lays out the four-stage "Founder Operating System".
  • Roadmap.tsx: Mounts a futuristic vertical timeline (2026 → 2028+), premium social buttons, and a calendar booking block (Calendly).

4. Design System & High-Fidelity UI Components

All components adhere to a strict dark glassmorphic UI standard, featuring deep black bases, frosted border borders, and micro-animations to create a premium, alive application texture.

🌗 Dynamic Theme System (Light & Dark)

  • State Management: next-themes controls the global theme preference, injecting the .dark class onto the root <html> tag. Hydration warnings are suppressed to prevent React mismatches.
  • Semantic CSS Variables: Hardcoded colors are entirely replaced by dynamic variables (--background, --foreground, --muted, etc.) defined in globals.css under :root and .dark scopes.
  • Intelligent Contrast: Components dynamically flip contrast priorities. For example, primary buttons use bg-foreground text-background to guarantee a dark button in light mode and a light button in dark mode.

🎨 Visual Theme Configuration (globals.css)

  • Colors: Primary backdrop uses semantic --background (pitch black #050505 in dark mode, white #ffffff in light mode), foreground content uses --foreground (#ededed in dark, #09090b in light).
  • Frosted Glass Elements: 
    .glass {
  background: rgba(255, 255, 255, 0.03);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.08);
}
.glass-panel {
  background: rgba(0, 0, 0, 0.4);
  backdrop-filter: blur(16px);
  border: 1px solid rgba(255, 255, 255, 0.05);
  box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
  border-radius: 1rem;
}

🧩 Custom Interactive UI Components

1. Glass Card (GlassCard.tsx)

This component behaves like a dynamic light-refracting card:

  • 3D Interactive Tilt: When hovering, it measures the mouse position relative to the card box, computing custom horizontal/vertical rotation variables. It smoothly tilts up to 8 degrees based on organic springs.
  • Cursor Spotlight & Border Highlight: Uses dynamic Framer Motion templates to paint radial highlights:
    • background: A dynamic radial gradient centered on the cursor path inside the card (rgba(255, 255, 255, 0.06)).
    • borderBackground: Generates a high-precision 1px border mask tracking the exact cursor entry point, giving the card a glowing boundary that follows the visitor's focus.

2. Magnetic Interactive Controllers (Button.tsx & MagneticButton.tsx)

  • Provides subtle physics: when the cursor gets close to a button, the button pulls towards the mouse slightly (strength = 40%), snapping back to the center on exit via rapid springs.
  • Utilizes a two-part combination:
    • MagneticButton handles outer positioning physics.
    • Button implements individual internal scaling, tap offsets, and color options (Default, Outline, Ghost, Glass).

3. Dynamic Fractal Noise Overlay (NoiseOverlay.tsx)

Applies a low-visibility (opacity-[0.03]) high-fidelity SVG fractal filter over the entire viewport with an overlay mix-blend-mode. It gives the digital portfolio an elegant physical paper/analog monitor texture.

4. Physical Count-Up Animation (Counter.tsx)

  • Monitors viewport state using Framer Motion's useInView.
  • Once visible, a custom spring runs from 0 to the target statistic. A transform hook parses this spring state character-by-character, updating the visible node to standard decimal points while removing unnecessary trailing decimals.

5. Scroll-Linked Progress Banner (ScrollProgress.tsx)

Calculates the scroll fraction from 0 to 1 across the root viewport. Projects this progress horizontally across a fixed 4px top bar using a tri-color gradient (Indigo → Violet → Indigo).

5. Interactive AI Twin & RAG Engine

A signature feature is the "AI Twin" Chatbot, which allows visitors to chat with an automated agent trained specifically on Tay Za's background. It uses a Retrieval-Augmented Generation (RAG) architecture locally in Next.js without requiring external database dependencies and streams responses using the Vercel AI SDK.

Technical RAG Workflow Diagram

sequenceDiagram
    autonumber
    actor User as Web Visitor
    participant Client as AiChat Component (Client via useChat)
    participant API as serverless api/chat (Next.js Node.js Route)
    participant GeminiEmbed as Google Gemini Embedding API
    participant Vectors as Local vector db (portfolio-embeddings.json)
    participant GeminiFlash as Google Gemini Flash API

    User->>Client: Types query (e.g. "Tell me about SecureXchange")
    Client->>API: POSTs payload { messages: [...] }
    
    rect rgb(20, 20, 35)
        note right of API: Security validations & rate limiting<br/>(Max 5 req/min, 1000 char cap)
    end
    
    API->>GeminiEmbed: Requests vector for message via gemini-embedding-001
    GeminiEmbed-->>API: Returns 768-dimensional float array
    
    rect rgb(20, 35, 20)
        note right of API: Computes Cosine Similarity against JSON vectors
    end
    
    API->>Vectors: Loads local precomputed array
    API->>API: Sorts similarities & extracts top 3 matches
    
    rect rgb(35, 20, 20)
        note right of API: Augments original question with matches
    end
    
    API->>GeminiFlash: Generates stream using streamText() with in-character prompt + context
    GeminiFlash-->>API: Returns generated response chunks
    
    API-->>Client: Returns streaming text response
    
    rect rgb(20, 20, 20)
        note left of Client: Vercel AI SDK native streaming rendering
    end
    
    Client-->>User: Displays styled Response (Markdown & Code blocks formatted)

Server Endpoint Validation (src/app/api/chat/route.ts)

  • IP-Based Rate Limiting: Employs an in-memory Map recording remote IP addresses. If an IP exceeds 5 requests within 60 seconds, the server rejects the request with a 429 Too Many Requests code, returning a friendly fallback message directing them to LinkedIn.
  • Payload Bounds: Restricts messages to 1000 characters, rejecting longer requests with 400 Bad Request.
  • Vector Engine:
    • Generates a 768-dimensional query vector using Google's gemini-embedding-001.
    • Reads src/data/portfolio-embeddings.json.
    • Computes Cosine Similarity manually using the following standard equation: 
      $$\text{Similarity} = \frac{\mathbf{A} \cdot \mathbf{B}}{\|\mathbf{A}\| \|\mathbf{B}\|} = \frac{\sum_{i=1}^{n} A_i B_i}{\sqrt{\sum_{i=1}^{n} A_i^2} \sqrt{\sum_{i=1}^{n} B_i^2}}$$
    • Sorts all entries, selects the top 3 most relevant matches, and joins them into an augmented system context block.
  • In-Character Response: Combines the system prompt defining Tay Za's persona with the retrieved matches, and generates a formatted response using gemini-flash-latest.
  • Fail-Safe Architecture: If the GEMINI_API_KEY is missing in the host system, the API degrades gracefully, prompting the user with standard developer contact buttons instead of crashing.

6. Embedding Precomputation Pipeline

The semantic database is built locally. Rather than querying an expensive, external cloud-hosted vector repository at runtime, embeddings are precomputed offline and committed directly as a static database array.

Data Structures

1. Raw Core Data (src/data/portfolio-knowledge.json)

Consists of specific markdown blocks detailing projects, market theses, and operational methodologies:

[
  {
    "id": "project-mobile-topup",
    "text": "Project: Mobile Top-up Automation (MyanTop). A highly available mobile top-up automation system..."
  }
]

2. Vector Output Data (src/data/portfolio-embeddings.json)

Constructed by the script, holding identical IDs along with the matching 768-dimensional floating-point vectors:

[
  {
    "id": "project-mobile-topup",
    "text": "Project: Mobile Top-up Automation...",
    "embedding": [
      0.0123512,
      -0.0825123,
      0.0039212
      // ... 768 values
    ]
  }
]

âš¡ Vector Generation Script (scripts/generate-embeddings.mjs)

To update the AI twin's knowledge base:

  1. Update descriptions or add new records inside src/data/portfolio-knowledge.json.
  2. Ensure you have the GEMINI_API_KEY set in your current terminal session.
  3. Run the generator script: 
    node scripts/generate-embeddings.mjs
  4. The script fetches embeddings for each item sequentially via Google's gemini-embedding-001 API and saves the new vector database file.

7. Environment Configuration & Local Setup

System Prerequisites

  • Node.js: Version 18.17.0 or higher
  • Package Manager: npm (default) or any preferred alternative (yarn, pnpm, bun)

Step-by-Step Installation

  1. Clone & Navigate:

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

  2. Install Project Dependencies:

    npm install

  3. Configure API Tokens:

    • Copy the template environment configuration file: 
      cp .env.example .env
    • Open .env and fill in your Gemini API Key: 
      GEMINI_API_KEY=AIzaSy...YourActualGeminiKey

  4. Run in Development Mode:

    npm run dev

    Open http://localhost:3000 to view the running, hot-reloading development environment.

8. Production Build & Deployment Guidelines

Code Quality Audits

Before deploying to production, run the code linting and formatting suites to verify strict typing and standard style rules:

npm run lint

Compilation Build Testing

Compile the React 19 pages into static components and API edge routes:

npm run build

This command compiles code, aggregates stylesheet rules using the Tailwind V4 PostCSS engine, typechecks files, and optimizes layout assets.

Deploying to Vercel

The Premium Portfolio is designed to run out-of-the-box on the Vercel Serverless Hosting Platform:

  1. Deploy via Vercel CLI: 
    npx vercel
  2. Define Environment Credentials: Ensure the GEMINI_API_KEY environment variable is configured in your project settings on the Vercel Dashboard before hitting the production build.
  3. Production Release: 
    npx vercel --prod

Documentation maintained by Antigravity and the core developer team. Last updated: May 2026.