Update README to reflect portfolio site details and structure

Author: gavinhon

README.md

@@ -1,9 +1,121 @@
-# React Application with Vite and Three.js
+# Gavin Hon Portfolio
 
-This repository contains a React application that utilizes Vite as the build tool and integrates Three.js for 3D graphics rendering. It serves as a starting point for developing interactive and visually engaging web applications.
+This is a single-page portfolio site built with React and Vite. It is designed as a content-driven personal site rather than a CMS-backed app: profile details, experience, education, links, and featured work are maintained directly in the source code.
 
-## Features
+The site combines a structured portfolio layout with a Three.js globe hero, grouped experience cards, and a light/dark theme that follows the user's device or browser preference.
 
-- React: A JavaScript library for building user interfaces.
-- Vite: A fast and lightweight development build tool for modern web applications.
-- Three.js: A JavaScript library for creating 3D graphics and animations in the browser.
+## Tech Stack
+
+- React 18 for the UI and section composition
+- Vite for local development and production builds
+- Three.js for the hero globe
+- GSAP for globe motion
+- Plain CSS for layout, theming, and responsive behavior
+- React Context for portfolio content and profile data
+
+## How It Is Built
+
+### Application structure
+
+- `src/main.jsx` mounts the React app
+- `src/App.jsx` composes the page sections and applies reveal-on-scroll behavior
+- `src/context/DataContext.jsx` stores the portfolio content model
+- `src/components/sections/` contains the main page sections:
+  - `Navbar`
+  - `Home`
+  - `About`
+  - `Work`
+  - `Credentials`
+  - `Footer`
+- `src/components/ThreeEarth.jsx` renders the globe used in the hero
+- `public/` contains static assets such as logos, favicon, social icons, and profile imagery
+
+### Content model
+
+The site content is driven from `src/context/DataContext.jsx`.
+
+This includes:
+
+- profile headline, summaries, links, and hero highlights
+- grouped work experience entries and company metadata
+- certifications and education
+- featured public links
+- skill tags and focus areas
+
+If you want to update role history, hero text, public links, or company logos, that is the main file to change.
+
+### Styling and theming
+
+- `src/index.css` defines the global design tokens and the light/dark theme variables
+- the site uses `prefers-color-scheme` to switch automatically between light and dark mode
+- `src/App.css` provides the shared shell, card, button, pill, and reveal styles
+- each section has its own CSS file for layout-specific styling
+
+The current visual direction uses:
+
+- a cool-toned grid background
+- glass-like cards with soft borders and shadows
+- a restrained defense-tech inspired palette
+- responsive layouts for desktop and mobile
+
+### Hero globe
+
+The hero section lazy-loads `ThreeEarth` so the main page content does not depend on the rendering bundle loading first.
+
+The globe implementation uses:
+
+- Three.js scene/camera/renderer setup
+- GSAP-based rotation animation
+- a separate rendering chunk configured in `vite.config.js`
+
+## Build and Run
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the local dev server:
+
+```bash
+npm run dev
+```
+
+Create a production build:
+
+```bash
+npm run build
+```
+
+Preview the production build locally:
+
+```bash
+npm run preview
+```
+
+## Build Configuration
+
+`vite.config.js` uses:
+
+- `@vitejs/plugin-react` for React support
+- `vite-plugin-string` for loading shader strings
+- manual chunking so `three` and `gsap` are split into a dedicated `rendering` bundle
+
+This keeps the main app bundle smaller and isolates the heavier visual code.
+
+## Notes for Maintenance
+
+- update portfolio content in `src/context/DataContext.jsx`
+- update section layout/styling in the matching file under `src/components/sections/`
+- update global theme behavior in `src/index.css` and `src/App.css`
+- update static assets such as logos and favicon in `public/`
+
+## Current Characteristics
+
+- single-page portfolio experience
+- sticky top navigation with section jump links
+- grouped company experience cards
+- responsive first-fold hero with globe backdrop
+- public-facing links to LinkedIn, GitHub, and selected work
+- system-based light and dark mode