External Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• api/index.ts
• hooks/useWakaTime.ts
• projects-cli/src/lib/gemini.ts
• lib/types.ts
• components/ui/WakaTimeDashboard.tsx
• pages/Stats.tsx

External Integrations represent the architectural layer responsible for connecting the portfolio system with third-party services. This module aggregates real-time coding metrics, social contribution data, and automated project analysis to provide a dynamic, data-driven representation of developer activity.

The system utilizes an Edge-based API layer (Hono) to proxy requests to external providers, ensuring secure credential management and performance through specialized caching mechanisms. Primary integrations include GitHub for repository statistics and contribution history, WakaTime for granular coding time metrics, and Google Gemini AI for automated project metadata extraction.
Sources: api/index.ts:1-25, projects-cli/src/lib/gemini.ts:1-40, pages/Stats.tsx:110-140

API Architecture and Proxy Layer

The project employs a Hono-based API deployed on Vercel Edge Runtime to handle all external communications. This layer acts as a secure middleware that injects environment variables (API keys and tokens) before forwarding requests to external endpoints.

Request Flow and Caching

To optimize performance and respect rate limits, the API implements a centralized caching and inflight request tracker.

The diagram shows the request lifecycle from the frontend through the Edge proxy to the external providers.
Sources: api/index.ts:27-100

Cache Configuration

The system distinguishes between general data and high-frequency updates through specific TTL (Time To Live) settings:

Cache Type	TTL (Duration)	Purpose
DEFAULT_CACHE_TTL	60 seconds	General project and status data
GH_CACHE_TTL	5 minutes	GitHub contributions and repository stats
FETCH_TIMEOUT	10 seconds	Maximum wait time for external responses

Sources: api/index.ts:46-50

GitHub Integration

The GitHub integration fetches comprehensive user profiles, repository statistics, and contribution calendars via both REST and GraphQL APIs.

Data Aggregation

The system retrieves data from multiple GitHub endpoints to build the GitHubStats object:

• User Endpoint: Provides public repo counts, followers, and following.
• Repos Endpoint: Aggregates stargazers_count across all public repositories.
• Events Endpoint: Filters PushEvent types to determine the lastCommit and mostActiveRepo.
• GraphQL API: Used for precise contributionCalendar data, including daily counts and levels (0-4).

GitHub Schema

The following data structure is utilized for rendering the Stats page:

Field	Type	Description
publicRepos	number	Total public repositories
totalStars	number	Sum of stars across all repos
totalCommits	number	Calculated via contribution calendar
lastCommit	object	Includes message, repo name, date, and URL
weeks	Array	2D array of GitHubContributionDay for heatmaps

Sources: lib/types.ts:79-115, api/index.ts:250-360, pages/Stats.tsx:15-50

WakaTime Integration

WakaTime integration provides real-time telemetry of coding activity, including language usage, editor preferences, and project-specific time tracking.

Synchronization Logic

The system polls two primary WakaTime endpoints:

1. /summaries: Aggregates the last 7 days of activity to calculate daily averages and best days.
2. /statusbar/today: Determines if the user is currently "Active" (Live Coding Status).

The sequence illustrates the transformation of raw WakaTime summaries into structured UI metrics.
Sources: api/index.ts:135-235, hooks/useWakaTime.ts:10-50, components/ui/WakaTimeDashboard.tsx:60-100

Gemini AI Integration

The system includes a CLI-based integration with Google Gemini (gemini-2.0-flash) for automated project analysis.

Metadata Extraction Pipeline

When a new project is added via projects-cli, the system performs the following steps:

1. File Gathering: Scans the directory for priority files (e.g., package.json, Cargo.toml, README.md) using glob patterns.
2. Signal Building: Generates a summary of file counts, top extensions, and detected dependency hints (e.g., React, Next.js).
3. LLM Analysis: Sends the signals and file content to Gemini with a strict JSON schema.

Analysis Schema

Gemini is constrained to a specific schema to ensure compatibility with the portfolio's Project type:

const PROJECT_SCHEMA = {
  type: Type.OBJECT,
  properties: {
    id: { type: Type.STRING },
    name: { type: Type.STRING },
    desc: { type: Type.STRING },
    stack: { type: Type.ARRAY, items: { type: Type.STRING } },
    status: { type: Type.STRING },
    icon: { type: Type.STRING }
  },
  required: ['id', 'name', 'desc', 'stack', 'status', 'icon']
}

Sources: projects-cli/src/lib/gemini.ts:30-100, projects-cli/src/lib/gemini.ts:315-340

Summary of Integration Hooks

Frontend components interact with these integrations through specialized React hooks that manage loading states and error handling.

Hook	Source File	External Dependency
useWakaTimeSummary	hooks/useWakaTime.ts	WakaTime /summaries
useWakaTimeStatus	hooks/useWakaTime.ts	WakaTime /statusbar
useGitHubStats	hooks/useGitHub.ts	GitHub REST/GraphQL
analyzeWithGemini	lib/gemini.ts	Google Gemini API

Sources: hooks/useWakaTime.ts:13, pages/Stats.tsx:11, projects-cli/src/lib/gemini.ts:315

External integrations in this project serve as the bridge between static portfolio content and the developer's living ecosystem. By leveraging Edge functions for security and AI for automation, the system maintains a high-fidelity representation of technical skills and activity with minimal manual overhead.