🚀 WomB0ComB0 Portfolio: Your Digital Canvas

An interactive and high-performance developer portfolio showcasing projects, real-time insights, and a dynamic online presence.

---

🗺️ Table of Contents

• ✨ Overview & Introduction
  • What is this Application?
  • Purpose & Goals
  • Target Audience
• 🌟 Feature Highlights
• 🏛️ Architecture & Design
  • High-Level Component Diagram
  • Core Components & Responsibilities
  • Technology Stack
• 🛠️ Getting Started
  • Prerequisites
  • Installation Steps
  • Configuration
    • Environment Variables (.env.local)
    • Sanity.io Setup
    • Firebase Setup
  • Running the Application
    • Development Mode
    • Production Build & Run
    • Running with Docker
• 💡 Usage & Workflows
  • Navigating the Portfolio
  • Command Palette (KBar)
  • Interacting with the Guestbook
  • Viewing Dynamic Content
  • Common CLI Commands
• ⚠️ Limitations, Known Issues & Future Roadmap
  • Current Limitations
  • Known Issues
  • Future Roadmap
• 🤝 Contributing & Development Guidelines
  • How to Contribute
  • Branching & Pull Request Guidelines
  • Code Style & Linting
  • Testing
  • Development Setup
• 📜 License, Credits & Contact
  • License
  • Acknowledgments
  • Contact
• 📚 Appendix
  • Changelog
  • FAQ (Frequently Asked Questions)
  • Troubleshooting Guide
  • API Reference

---

✨ Overview & Introduction

[⬆️ Back to Top]

What is this Application?

This project is a sophisticated, interactive personal portfolio application built with Next.js (App Router), TypeScript, and a robust API backend powered by Elysia.js. It serves as a central hub for displaying a developer's profile, skills, resume, blog posts, projects, and various real-time statistics (e.g., Spotify activity, coding insights from Wakatime, GitHub stats, Discord presence via Lanyard). The application is designed to be highly dynamic, engaging, and performant.

Purpose & Goals

The primary goals of this application are:

• Showcase Expertise: Present a comprehensive and visually appealing overview of the developer's professional journey, skills, and projects.
• Dynamic Engagement: Provide interactive elements such as a guestbook, real-time data visualizations, and an intuitive command palette to enhance user experience.
• Technical Proficiency: Demonstrate advanced modern web development practices, including server-side rendering, API integrations, robust error handling, security measures, and PWA capabilities.
• Centralized Presence: Consolidate disparate online activities (blog, social media, coding stats) into a single, cohesive platform.

Target Audience

• Recruiters & Hiring Managers: To quickly assess skills, experience, and project quality.
• Potential Collaborators: To find synergy for joint projects or initiatives.
• Fellow Developers: To inspire, share knowledge, and explore technical implementations.
• General Visitors: Anyone interested in the developer's work, thoughts, or online presence.

---

🌟 Feature Highlights

[⬆️ Back to Top]

This portfolio is packed with features designed to provide a rich and informative user experience:

🚀 Performance & UX

• Blazing Fast Performance: Leverages Next.js App Router for optimal server-side rendering (SSR), static site generation (SSG), and client-side navigation.
• Modern & Responsive UI: Built with Tailwind CSS, shadcn/ui, and custom MagicUI components for a beautiful, adaptive design across devices.
• Progressive Web App (PWA): Installable for a native app-like experience, offering offline capabilities and faster load times.
• Command Palette (KBar): A powerful Cmd+K (or Ctrl+K) interface for quick navigation and actions throughout the site.

📝 Content & Data Management

• Sanity.io CMS Integration: Effortlessly manage projects, experiences, certifications, and other static content via a headless CMS, ensuring content creators have full control without touching code.
• Hashnode Blog Integration: Fetches and displays blog posts directly from a Hashnode blog, centralizing content.
• Interactive Guestbook: Users can sign in (via Firebase Auth) to leave messages, fostering community engagement and providing social interaction.
• Dynamic Image Optimization: Images are optimized and served efficiently using Next.js Image component and Sanity's image CDN.

📊 Real-time Data & Insights

• Spotify Now Playing: Displays current Spotify listening activity in real-time.
• Top Artists/Tracks: Showcases frequently listened-to music from Spotify.
• GitHub Statistics: Dynamically displays profile stats and pinned repositories from GitHub.
• Wakatime Coding Stats: Integrates with Wakatime to visualize coding activity, languages, and editors.
• Discord Presence (Lanyard): Shows current Discord status and activity, providing a live snapshot of online presence.
• Google Analytics & Vitals: Integrated for performance monitoring and user behavior tracking, with client-side Web Vitals reporting.

🔒 Security & Reliability

• CSRF Protection: Protects against cross-site request forgery attacks on API endpoints.
• Rate Limiting: Prevents abuse and ensures API stability by limiting request frequency.
• IP Banlist: Blocks malicious IP addresses from accessing sensitive API routes.
• Edge-Optimized APIs: A dedicated backend built with Elysia.js (running on Edge functions) for high-performance, low-latency API routes, handling external integrations and guestbook submissions securely.

⚙️ Development & Maintenance

• Comprehensive Tooling: Integrates Bun for fast dependency management and script execution, Biome for linting/formatting, Vitest for unit testing, and Playwright for end-to-end testing.
• Docker Support: Ready-to-use Dockerfile and docker-compose.yml for easy containerized deployment.
• SEO Ready: Dynamic Sitemap & Robots.txt generation, structured data, and Open Graph (OG) image generation for optimal search engine indexing and social media sharing.
• Strict Type Safety: Fully built with TypeScript, ensuring robust code and fewer runtime errors.

---

🏛️ Architecture & Design

[⬆️ Back to Top]

The WomB0ComB0 Portfolio application follows a modern, distributed architecture leveraging a hybrid approach of server-side rendering (SSR), static site generation (SSG), and API routes, orchestrated by Next.js and Elysia.js.

High-Level Component Diagram

This diagram illustrates the primary components and their interactions within the application ecosystem.

flowchart TD
    A["Client Browser"]
    B["Next.js App"]
    C["Elysia.js API Gateway"]
    D["Sanity.io CDN"]
    E["Firebase"]
    F["Redis"]

    A -->|"Navigates/Interacts"| B
    B -->|"Renders Pages (SSR/SSG)"| A
    B -->|"Calls API Routes"| C
    B -->|"Fetches CMS Content"| D
    C -->|"Authenticates/Stores Guestbook"| E
    C -->|"Caches Data"| F

    %% External APIs as explicit nodes
    C -->|"Fetches Real-time Data"| GH
    C -->|"Fetches Real-time Data"| SP
    C -->|"Fetches Real-time Data"| WK
    C -->|"Fetches Real-time Data"| LY
    C -->|"Fetches Real-time Data"| HN

    %% Group serverless bits
    subgraph EDGE["Serverless Functions (Vercel/Edge)"]
        B
        C
    end

    %% Group data/external services
    subgraph DATA["Data Stores & External Services"]
        D
        E
        F
        subgraph EXT["External APIs"]
            GH["GitHub"]
            SP["Spotify"]
            WK["Wakatime"]
            LY["Lanyard"]
            HN["Hashnode"]
        end
    end

    classDef pink fill:#f9f,stroke:#333,stroke-width:2px
    classDef blue fill:#ccf,stroke:#333,stroke-width:2px
    classDef green fill:#afa,stroke:#333,stroke-width:2px
    classDef purple fill:#fcf,stroke:#333,stroke-width:2px
    classDef lightblue fill:#ddf,stroke:#333,stroke-width:2px

    class B pink
    class C blue
    class D green
    class E purple
    class F lightblue

Loading

Core Components & Responsibilities

1. Next.js Application (src/app/, src/components/, src/lib/, src/hooks/)

   • Frontend Rendering: Manages all client-side and server-side rendering using the App Router. Responsible for displaying the UI, handling navigation, and providing interactive elements.
   • Data Fetching: Initiates requests to the Elysia.js API or Sanity.io CDN for dynamic content. Utilizes React Server Components (RSC) and SWR caching for efficient data management.
   • UI/UX: Integrates Tailwind CSS, shadcn/ui, and custom MagicUI components for a polished, responsive, and animated user interface.
   • PWA & SEO: Handles manifest, service worker registration, sitemap, robots.txt, and Open Graph meta tags.

2. Elysia.js API Gateway (src/app/api/[[...route]]/elysia.ts, src/app/api/v1/[[...route]]/elysia.ts)

   • Centralized Backend: A lightweight, high-performance API backend built with Elysia.js, designed to run efficiently on Edge functions.
   • External Integrations: Acts as a proxy and aggregator for various external APIs (Spotify, GitHub, Wakatime, Lanyard, Hashnode), abstracting their complexities and providing a unified interface.
   • Guestbook Management: Handles guestbook message submission, storage (Firebase), and retrieval.
   • Security Layer: Implements CSRF protection, rate limiting, and an IP banlist to secure API endpoints.
   • Data Caching: Leverages Redis for caching frequently accessed data from external APIs to reduce load and improve response times.

3. Sanity.io CMS (sanity.config.ts, src/sanity/)

   • Headless Content Management: Provides a flexible content management system for structured data such as projects, experiences, certifications, and resume details.
   • Content API: Offers a GraphQL API (or GROQ query language) to fetch content, which Next.js consumes.
   • Sanity Studio: A customizable UI for content editors to manage and publish content.

4. Firebase (src/core/firebase.ts, src/core/firebase-admin.ts)

   • Authentication: Manages user authentication for interactive features like the guestbook.
   • Firestore: Used as a NoSQL database for storing dynamic user-generated content, specifically guestbook messages.

5. Redis (src/classes/redis.ts)

   • Distributed Cache: Utilized by the Elysia.js API to cache responses from external services, minimizing repeated API calls and improving performance.

Technology Stack

Category	Technology	Description
Frontend	Next.js (App Router)	React framework for full-stack applications, enabling SSR, SSG, and API routes.
	React	JavaScript library for building user interfaces.
	TypeScript	Statically typed superset of JavaScript for enhanced code quality and maintainability.
	Tailwind CSS	Utility-first CSS framework for rapid UI development.
	shadcn/ui	Collection of re-usable components built with Radix UI and Tailwind CSS.
	MagicUI	Custom animations and interactive UI components.
	Jotai	Primitive and flexible state management for React.
Backend API	Elysia.js	Fast, lightweight, and type-safe web framework for building HTTP APIs, optimized for Bun and Edge environments.
	Redis	In-memory data store used for caching API responses.
CMS	Sanity.io	Headless CMS for structured content management (projects, experiences, certifications, blog settings).
Database/Auth	Firebase (Auth, Firestore)	Google's platform for user authentication and real-time NoSQL database (for guestbook messages).
Runtime	Bun	All-in-one JavaScript runtime, bundler, transpiler, and package manager, used for development and build processes.
Testing	Vitest	Fast unit and integration test framework.
	Playwright	End-to-end testing framework for robust browser automation.
Code Quality	Biome	All-in-one toolchain for web projects (formatter, linter).
	ESLint	Pluggable linting utility for JavaScript and TypeScript.
	Prettier	Opinionated code formatter.
Deployment	Vercel	Platform for frontend frameworks, enabling seamless deployment of Next.js applications and Edge functions.
	Docker	Containerization platform for consistent development and deployment environments.
CI/CD	GitHub Actions	Automation workflows for continuous integration and deployment (linting, testing, building, Docker images).
Misc. Integrations	GitHub, Spotify, Wakatime, Lanyard, Hashnode	APIs for fetching dynamic profile information, music activity, coding statistics, Discord status, and blog posts.

---

🛠️ Getting Started

[⬆️ Back to Top]

Follow these steps to set up and run the WomB0ComB0 Portfolio application locally.

Prerequisites

Before you begin, ensure you have the following installed:

• Bun (recommended): Version ^1.0.0 or higher.
  • Install via: curl -fsSL https://bun.sh/install | bash
• Node.js: Version ^18.0.0 or higher (if not using Bun).
  • Install via nvm or your preferred method.
• Git: For cloning the repository.
• Sanity CLI: For managing your Sanity.io project.
  • Install via: bun add --global @sanity/cli (or npm i -g @sanity/cli)
• Firebase CLI: For managing your Firebase project.
  • Install via: bun add --global firebase-tools (or npm i -g firebase-tools)
• Docker & Docker Compose: (Optional) For running the application in a containerized environment.

Installation Steps

1. Clone the repository:

   git clone https://github.com/WomB0ComB0/portfolio.git
   cd portfolio

2. Install dependencies: Using Bun (recommended):

   bun install

   Using npm (alternative):

   npm install

3. Generate GitHub GraphQL schema (required for some APIs):

   bun run codegen

Configuration

The application requires several environment variables for API keys, service integrations, and authentication.

Environment Variables (.env.local)

Create a .env.local file in the root of the project by copying from .env.example:

cp .env.example .env.local

Edit .env.local and fill in the values for the following:

Required Environment Variables (Click to expand)

# Application Configuration
NEXT_PUBLIC_APP_URL="http://localhost:3000" # Your deployed app URL (for canonical links, etc.)
NEXT_PUBLIC_APP_NAME="WomB0ComB0 Portfolio"
NEXT_PUBLIC_APP_VERSION="1.0.0"

# Sanity.io CMS (Headless CMS for content)
NEXT_PUBLIC_SANITY_PROJECT_ID="your_sanity_project_id"
NEXT_PUBLIC_SANITY_DATASET="production" # Or your custom dataset name
NEXT_PUBLIC_SANITY_API_VERSION="2024-05-23" # Recommended: use current date
NEXT_PUBLIC_SANITY_CDN_ENABLED="true" # Set to 'false' during development if you need freshest data
SANITY_API_READ_TOKEN="your_sanity_read_token" # Required for some server-side queries

# Firebase (Authentication and Guestbook)
NEXT_PUBLIC_FIREBASE_API_KEY="your_firebase_api_key"
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN="your_firebase_auth_domain"
NEXT_PUBLIC_FIREBASE_PROJECT_ID="your_firebase_project_id"
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET="your_firebase_storage_bucket"
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID="your_firebase_messaging_sender_id"
NEXT_PUBLIC_FIREBASE_APP_ID="your_firebase_app_id"
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID="your_firebase_measurement_id" # Optional, for analytics

FIREBASE_PRIVATE_KEY_ID="your_firebase_private_key_id"
FIREBASE_PRIVATE_KEY="your_firebase_private_key" # IMPORTANT: Use actual key or base64 encoded string with \n for newlines
FIREBASE_CLIENT_EMAIL="your_firebase_client_email"
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_AUTH_URI="your_firebase_auth_uri"
FIREBASE_TOKEN_URI="your_firebase_token_uri"
FIREBASE_AUTH_PROVIDER_X509_CERT_URL="your_firebase_auth_provider_x509_cert_url"
FIREBASE_CLIENT_X509_CERT_URL="your_firebase_client_x509_cert_url"
FIREBASE_UNIVERSE_DOMAIN="your_firebase_universe_domain"

# External API Keys (for real-time data)
GITHUB_ACCESS_TOKEN="your_github_personal_access_token" # Required for GitHub stats and pinned repos
NEXT_PUBLIC_GITHUB_USERNAME="WomB0ComB0" # Your GitHub username

SPOTIFY_CLIENT_ID="your_spotify_client_id"
SPOTIFY_CLIENT_SECRET="your_spotify_client_secret"
SPOTIFY_REFRESH_TOKEN="your_spotify_refresh_token" # Guide to get: https://developer.spotify.com/documentation/general/guides/authorization-guide/

NEXT_PUBLIC_WAKATIME_USERNAME="your_wakatime_username" # Your Wakatime username
WAKATIME_API_KEY="your_wakatime_api_key"

NEXT_PUBLIC_LANYARD_USER_ID="your_discord_user_id" # Your Discord user ID for Lanyard integration

# Optional: Google Analytics
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID="G-XXXXXXXXXX" # Your Google Analytics Measurement ID

# Redis (for API caching)
REDIS_URL="redis://localhost:6379" # Or your deployed Redis instance URL

# Elysia.js API Gateway Security
API_SECRET_KEY="a_long_random_string_for_api_signature" # Important for securing API routes
# You can generate a random string using `node -e "console.log(crypto.randomBytes(32).toString('hex'))"`

Sanity.io Setup

1. Create a Sanity project: If you don't have one, navigate to the sanity directory and run:

   cd sanity
   sanity init
   # Follow the prompts: create new project, choose "Blog" or "Empty project" and then migrate schemas.
   # Select a dataset name (e.g., 'production').
   # Deploy your studio when prompted (this makes it accessible online).

2. Deploy Sanity schemas: From the sanity directory:

   sanity deploy
   # This ensures your studio has the correct schema definitions from src/sanity/schemaTypes

3. Configure environment variables for Sanity: Update NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET in .env.local with the values from your Sanity project. Create a "Read Token" in your Sanity project settings (manage.sanity.io), and set it as SANITY_API_READ_TOKEN in .env.local.

4. Import initial data: You'll need to populate your Sanity studio with content (projects, experiences, etc.) either manually or via a Sanity import script if you have existing data.

Firebase Setup

1. Create a Firebase project: Go to the Firebase Console and create a new project.

2. Enable Authentication: In your Firebase project, navigate to "Authentication" and enable the desired sign-in methods (e.g., Google, Email/Password).

3. Set up Firestore: In your Firebase project, navigate to "Firestore Database" and create a new database. Set up security rules to allow authenticated users to read and write to a messages collection. A basic rule for testing might be:

   rules_version = '2';
   service cloud.firestore {
     match /databases/{database}/documents {
       match /messages/{messageId} {
         allow read, write: if request.auth != null;
       }
     }
   }
   

4. Configure Firebase environment variables:

   • Client-side (NEXT_PUBLIC_FIREBASE_...): In your Firebase project settings, add a new web app and copy its configuration to your .env.local file.
   • Server-side (FIREBASE_...): For Firebase Admin SDK, go to "Project settings" -> "Service accounts" -> "Generate new private key." Download the JSON file. Extract the private_key, private_key_id, client_email, client_id, auth_uri, token_uri, auth_provider_x509_cert_url, client_x509_cert_url, and universe_domain into your .env.local. Ensure FIREBASE_PRIVATE_KEY has \n replaced with actual newlines if base64 encoded.

Running the Application

Development Mode

To run the Next.js application in development mode with hot-reloading:

1. Start the Next.js development server:

   bun dev

   The application will be accessible at http://localhost:3000.

2. (Optional) Start the Sanity Studio if you need to manage content locally: In a separate terminal, navigate to the sanity directory and run:

   cd sanity
   bun sanity start

   The Sanity Studio will typically be accessible at http://localhost:3333.

Production Build & Run

To build the application for production and run it:

1. Build the Next.js application:

   bun build

2. Start the production server:

   bun start

   The application will run in production mode, typically on port 3000.

Running with Docker

The project includes Docker support for containerized deployment.

1. Build the Docker image:

   docker compose build

2. Run the Docker container:

   docker compose up

   The application will be available at http://localhost:3000. If you need to stop it, use docker compose down.

Using Docker for Sanity Studio & Redis (Advanced) (Click to expand)

The docker-compose.yml also includes a Redis service for local caching and can be extended to include a Sanity Studio service if desired, though Sanity Studio is often run locally via CLI or deployed.

To include Redis in your local development environment:

1. Ensure REDIS_URL="redis://redis:6379" is set in your .env.local if you're running the app in Docker, or redis://localhost:6379 if running Next.js locally and Redis in Docker.
2. Run docker compose up -d redis to start just the Redis service in the background.

---

💡 Usage & Workflows

[⬆️ Back to Top]

The WomB0ComB0 Portfolio is designed for intuitive navigation and interaction.

Navigating the Portfolio

• Main Navigation: Use the header navigation links to jump between sections like Home, Projects, Experience, Blog, Certifications, Guestbook, Spotify, Stats, and Resume.
• Mobile Menu: On smaller screens, a hamburger icon (typically top-right) reveals the full navigation menu.
• Dynamic Links: Many sections feature dynamic links (e.g., clicking on a project card to see its detail page, or an experience entry).
• Back to Top: Every major section in this README has a [[⬆️ Back to Top](#️-table-of-contents)] link for quick navigation.

Command Palette (KBar)

• Activate: Press Cmd+K (macOS) or Ctrl+K (Windows/Linux) anywhere on the site.
• Search: Start typing to filter available commands and navigation links.
• Actions: The palette allows you to quickly navigate to different pages, toggle themes, or perform other defined actions without extensive clicking.

Interacting with the Guestbook

1. Navigate: Go to the /guestbook page.
2. Sign In: Click the "Sign in with Google" or similar button to authenticate using Firebase.
3. Leave a Message: Once signed in, a text area will appear, allowing you to compose and submit your message.
4. View Messages: All public messages left by users will be displayed on the page.

Viewing Dynamic Content

• Projects (/projects): Browse a list of showcased projects. Each project card leads to a detailed page with descriptions, technologies, and images/videos, all managed via Sanity.io.
• Experience (/experience): See a timeline or list of professional experiences, including roles, responsibilities, and achievements, also sourced from Sanity.io.
• Spotify (/spotify): Observe real-time "Now Playing" status and discover the developer's top artists and tracks.
• Stats (/stats): A dashboard displaying various real-time statistics:
  • GitHub: Repository activity, stars, and contributions.
  • Wakatime: Coding activity breakdown by language, editor, and OS.
  • Discord (Lanyard): Current online status and gaming activity.

Common CLI Commands

The package.json contains several useful scripts:

• bun dev: Starts the Next.js development server.
• bun build: Compiles the Next.js application for production.
• bun start: Starts the Next.js production server.
• bun lint: Runs linting checks using Biome and ESLint.
• bun lint:fix: Automatically fixes linting errors.
• bun format: Formats code using Biome and Prettier.
• bun format:check: Checks for formatting issues.
• bun test: Runs unit and integration tests with Vitest.
• bun test:e2e: Runs end-to-end tests with Playwright.
• bun sanity start: Starts the Sanity Studio development server.
• bun sanity deploy: Deploys Sanity schemas to your Sanity project.
• bun typecheck: Runs TypeScript type checking.
• bun codegen: Generates GitHub GraphQL schema types.
• bun cleanup: Removes temporary files and build artifacts.
• bun audit: Runs security audits on dependencies.
• bun package-cost: Analyzes the size of installed packages.

---

⚠️ Limitations, Known Issues & Future Roadmap

[⬆️ Back to Top]

Current Limitations

• External API Rate Limits: Reliance on free tiers of external APIs (Spotify, GitHub, Wakatime) may lead to occasional rate limiting, especially with high traffic. Caching is implemented to mitigate this, but persistent high load could still be an issue.
• Sanity.io Dependency: The core content of the portfolio (projects, experience, certifications) is entirely dependent on Sanity.io. Without a configured Sanity project, these sections will be empty.
• Guestbook Authentication: Currently, only Google authentication is readily configured for the guestbook. Extending to other providers (GitHub, Email/Password) would require additional Firebase setup.
• Offline Functionality: While PWA is enabled, complex dynamic content (real-time stats, guestbook interaction) naturally requires an internet connection. Static content will be cached.

Known Issues

• Initial Load Latency for Real-time Data: On the first load, some external API calls might introduce a slight delay before data such as Spotify or Wakatime stats fully populate, as they hit cold caches. This is minimized with server-side caching and streaming.
• Potential for Stale Data: Although caching is implemented, in rare cases, extremely recent updates to external services (e.g., a Spotify song just changed) might not reflect immediately due to cache TTL (Time-To-Live).

Future Roadmap

The following enhancements and features are planned or under consideration:

• More API Integrations: Explore integrating more developer-centric platforms like LeetCode, Codeforces, or Dev.to for additional profile insights.
• Advanced Blog Features: Implement full-text search for blog posts, categories, tags, and potentially an integrated commenting system.
• AI-Powered Features: Explore integrating AI for content generation suggestions within the Sanity Studio or for personalized content recommendations.
• Enhanced Interactivity:
  • Interactive globe for "Places I've visited."
  • More sophisticated animations and micro-interactions.
• Admin Dashboard: A basic admin panel to manage guestbook messages, IP bans, and cache invalidation without direct database access.
• Improved Error Reporting: Integrate with a service like Sentry or LogRocket for more granular error monitoring and session replays.
• Performance Optimizations: Continuous efforts to reduce bundle size, optimize image loading, and improve server response times.
• Internationalization (i18n): Support for multiple languages to broaden audience reach.
• Webhooks for Sanity: Implement webhooks to trigger automatic revalidation of Next.js pages when Sanity content is updated, ensuring faster content updates without manual redeployment.

---

🤝 Contributing & Development Guidelines

[⬆️ Back to Top]

Contributions are welcome! Whether it's reporting a bug, suggesting a new feature, or submitting a pull request, your help is appreciated.

How to Contribute

1. Fork the repository: Start by forking the WomB0ComB0/portfolio repository to your GitHub account.

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/portfolio.git
   cd portfolio

3. Create a new branch: Choose a descriptive branch name (e.g., feat/add-dark-mode, fix/guestbook-bug).

   git checkout -b your-feature-branch-name

4. Make your changes: Implement your feature or bug fix.

5. Test your changes: Run bun test and bun test:e2e to ensure your changes haven't introduced regressions.

6. Run linters and formatters:

   bun lint:fix
   bun format

7. Commit your changes: Write clear and concise commit messages.

   git commit -m "feat: Add new feature"

8. Push to your fork:

   git push origin your-feature-branch-name

9. Open a Pull Request (PR):

   • Go to the original WomB0ComB0/portfolio repository on GitHub.
   • You should see a prompt to open a pull request from your recently pushed branch.
   • Provide a detailed description of your changes, including why they are necessary and how they were implemented.
   • Reference any relevant issues.

Branching & Pull Request Guidelines

• Branch Naming: Use feat/, fix/, docs/, refactor/, chore/ prefixes (e.g., feat/implement-new-api).
• Commit Messages: Follow Conventional Commits guidelines.
• Pull Request Description: Clearly explain the purpose of the PR, the changes made, and any potential side effects. Include screenshots or GIFs for UI changes.
• Code Review: All PRs require at least one approval before merging. Be responsive to feedback.

Code Style & Linting

We use a combination of Biome, ESLint, and Prettier to maintain a consistent code style.

• Biome: Used for overall project formatting and linting (biome.json).
• ESLint: Specific rules for React, Next.js, and TypeScript (.eslintrc.json).
• Prettier: For final code formatting (.prettierrc.json).

Ensure your code adheres to these standards by running:

bun lint:fix
bun format

Testing

• Unit & Integration Tests: Located in src/__tests__/ and run using Vitest.

  bun test

• End-to-End Tests: Located in src/e2e/ and run using Playwright.

  bun test:e2e

  These tests require the application to be running (e.g., via bun dev or bun start) or a bun build before bun test:e2e.

Development Setup

For a full local development setup, you'll want to run:

1. Application: bun dev
2. Sanity Studio: cd sanity && bun sanity start (in a separate terminal)
3. Firebase Emulators: (Optional, for advanced local Firebase development) firebase emulators:start

---

📜 License, Credits & Contact

[⬆️ Back to Top]

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• Next.js: The foundational framework for this portfolio.
• Elysia.js: For providing a powerful and efficient API gateway.
• Sanity.io: For enabling flexible content management.
• Tailwind CSS & shadcn/ui: For the beautiful and responsive UI components.
• MagicUI: For delightful animations and interactive elements.
• Bun: For super-fast development workflows.
• Firebase: For robust authentication and database services.
• All open-source contributors and package maintainers whose work made this project possible.

Contact

Have questions or want to connect?

• GitHub: @WomB0ComB0
• Portfolio Website: (Once deployed) Check NEXT_PUBLIC_APP_URL in .env.local

---

📚 Appendix

[⬆️ Back to Top]

Changelog

View Recent Updates (Click to expand)

v1.0.0 - (Date of Initial Release / This README Generation)

• Initial comprehensive release of the WomB0ComB0 Portfolio.
• Core features: Next.js App Router, Elysia.js API, Sanity.io CMS.
• Integrations: Spotify, GitHub, Wakatime, Lanyard.
• Interactive elements: Guestbook, Command Palette.
• Robust security measures: CSRF, Rate Limiting, IP Banlist.
• Extensive testing: Vitest (unit/integration), Playwright (E2E).
• Deployment readiness: Docker support, Vercel configuration.

FAQ (Frequently Asked Questions)

Q: How do I update my portfolio content? (Click to expand)

A: All static content (projects, experiences, certifications, blog settings) is managed through Sanity.io. Access your Sanity Studio (e.g., `https://your-project-id.sanity.studio/`) to make changes. Once changes are published, the Next.js application will fetch the updated content. For immediate revalidation on Vercel, consider setting up Sanity webhooks.

Q: Can I self-host this application? (Click to expand)

A: Yes! The application is designed to be highly portable. You can use the provided `Dockerfile` and `docker-compose.yml` to deploy it on any platform that supports Docker containers (e.g., AWS, GCP, Azure, DigitalOcean, a private VPS). Remember to configure all environment variables correctly for your hosting environment.

Q: My real-time stats (Spotify, Wakatime) aren't showing up. What should I check? (Click to expand)

A: 1. **Environment Variables:** Double-check that all `SPOTIFY_`, `WAKATIME_`, `GITHUB_ACCESS_TOKEN`, and `LANYARD_USER_ID` environment variables are correctly set in your `.env.local` file. 2. **API Keys/Tokens:** Ensure your Spotify refresh token, Wakatime API key, and GitHub access token are valid and have the necessary permissions. Spotify refresh tokens can expire, requiring re-generation. 3. **Internet Connection:** Confirm that the server running the application has outbound internet access to reach these external APIs. 4. **Rate Limits:** If you're frequently hitting these APIs, you might be temporarily rate-limited. Wait a bit and try again. Caching is in place to minimize this. 5. **Elysia.js API:** Verify that the Elysia.js API routes (e.g., `/api/v1/now-playing`) are responding correctly. You can try accessing them directly in your browser or with `curl` if running locally.

Q: How do I clear the local cache? (Click to expand)

A: If you're using Redis for caching, you can clear its data by restarting the Redis service or by using a Redis client to `FLUSHDB` or `FLUSHALL`. For the Next.js build cache, running `bun cleanup` will remove `.next/` and other temporary build artifacts.

Troubleshooting Guide

Common Issues & Solutions (Click to expand)

• Error: bun command not found: Ensure Bun is installed correctly and its binary is in your system's PATH. If not using Bun, switch to npm or yarn commands.
• Error: Environment variables missing: Review the Configuration section and ensure all required variables in .env.local are set. Pay special attention to complex variables like FIREBASE_PRIVATE_KEY.
• Sanity Studio not loading/schemas outdated:
  1. Navigate to the sanity directory.
  2. Run sanity deploy to push your local schemas to your Sanity project.
  3. Ensure NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET in .env.local match your Sanity project settings.
• API routes returning 401/403 errors:
  1. Check the API_SECRET_KEY in .env.local for consistency between client and server/API.
  2. Verify Firebase authentication setup and rules for the guestbook.
  3. Ensure SANITY_API_READ_TOKEN is correctly set if you are querying private Sanity content on the server.
  4. Check the API gateway's logs for more specific error messages (e.g., rate limit exceeded, IP banned).
• Playwright tests failing on fresh install: Ensure you have run bun install to install Playwright browsers. If not, try bun playwright install. Also, ensure the application is running (bun dev or bun start) before running bun test:e2e.
• Slow Development Server: Try deleting the .next and node_modules (or bun.lockb) directories and reinstalling dependencies. bun cleanup helps.

API Reference

The Elysia.js API endpoints are self-documented using Swagger/OpenAPI.

To view the interactive API documentation:

1. Start the Next.js development server (which also runs the Elysia API via Next.js API routes): bun dev
2. Navigate your browser to http://localhost:3000/api/swagger (or http://localhost:3000/api/v1/swagger for v1 APIs).

This will display the Swagger UI, allowing you to explore all available endpoints, their expected parameters, and response schemas.