API Endpoints

Relevant source files

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

• api/index.ts
• lib/types.ts
• hooks/useWakaTime.ts
• data/projects/projects.json
• components/ui/WakaTimeDashboard.tsx
• pages/Stats.tsx

The API system in the pcstyledev project provides a backend interface for retrieving project metadata, real-time coding statistics via WakaTime, and contribution data from GitHub. Built using the Hono framework and optimized for Vercel Edge Runtime, the API serves as a middle layer that aggregates data from external providers and local JSON data stores to power the portfolio's frontend components.

The API implements robust features including a custom caching mechanism, in-flight request tracking to prevent duplicate fetches, and global logging middleware. It manages sensitive credentials through environment variables and enforces validation before processing requests to external services.

Sources: api/index.ts:1-20, package.json:13-15

Core Architecture and Middleware

The API is initialized as a Hono application with a base path of /api. It utilizes several middleware components to ensure security, observability, and performance across all routes.

• Runtime Configuration: The API is explicitly configured to run on the edge runtime for low-latency responses.
• CORS: Global Cross-Origin Resource Sharing is enabled to allow frontend access.
• Logging: A global logger tracks every request, assigning a unique requestId and measuring duration.
• Caching & In-flight Tracking: The system uses a Map-based cache and an inflight tracker to deduplicate concurrent requests to external APIs like WakaTime and GitHub.

The flow demonstrates the request lifecycle including middleware validation and the caching strategy.
Sources: api/index.ts:14-80

Project Endpoints

These endpoints manage the retrieval of project data stored in the local repository. The data is derived from a static JSON file but served via the API to provide a consistent interface for the frontend.

Endpoint	Method	Description
/api/projects	GET	Returns a full list of projects defined in projects.json.
/api/projects/:id	GET	Returns metadata for a specific project by its unique ID.
/api/projects/meta	GET	Returns metadata about the project collection, including count and last update timestamp.

The /api/projects endpoints utilize standard HTTP caching headers (s-maxage=3600) to optimize delivery.
Sources: api/index.ts:100-118, data/projects/projects.json:1-350

WakaTime Integration

The WakaTime endpoints provide live coding statistics. The API transforms raw data from the WakaTime API into structured formats defined in the system's type definitions.

/api/wakatime/summary

Fetches coding activity for the last 7 days. It aggregates total seconds, calculates daily averages, and maps activity to languages, editors, and specific projects.

/api/wakatime/status

Provides a "live" status update based on the user's current heartbeats (activity today). It identifies if the user is currently active and which project/language they are using.

GitHub Integration

The GitHub endpoints utilize the GitHub GraphQL API (v4) and REST API (v3) to retrieve contribution data and general profile statistics.

/api/github/contributions

Uses a GraphQL query to fetch the contributionCalendar. This data powers the heatmap visualizations on the stats page. It maps GitHub's contribution levels (NONE, FIRST_QUARTILE, etc.) to numeric values (0-4).

/api/github/stats

Aggregates data from multiple GitHub sources:

1. User Profile: Public repos, followers, and following counts.
2. Repositories: Calculates total stars across all public repos.
3. Events: Analyzes public events to determine the lastCommit (message, repo, date) and the mostActiveRepo based on commit volume.
4. GraphQL: Retrieves the total contribution count for the user.

Sources: api/index.ts:212-328, pages/Stats.tsx:10-100, lib/types.ts:57-86

Health and Utility Endpoints

The API includes utility routes for system monitoring and environmental validation.

Endpoint	Method	Logic
/api/health	GET	Validates if WAKATIME_API_KEY, GITHUB_TOKEN, and GITHUB_USERNAME are configured. Returns status: ok or degraded.
/api/*	ALL	Catch-all route returning a 404 error for undefined paths.

Sources: api/index.ts:82-93, api/index.ts:331

Data Models

The API utilizes TypeScript interfaces to ensure consistency between external data processing and frontend consumption.

GitHubStats Interface

export interface GitHubStats {
  publicRepos: number
  followers: number
  following: number
  totalStars: number
  totalCommits?: number
  lastCommit?: {
    message: string
    repo: string
    date: string
    url: string
  }
  mostActiveRepo?: {
    name: string
    url: string
    commits: number
  }
}

Sources: lib/types.ts:71-86

WakaTimeSummary Interface

export interface WakaTimeSummary {
  totalSeconds: number
  totalHours: number
  dailyAverage: number
  languages: WakaTimeLanguage[]
  editors: WakaTimeEditor[]
  projects: WakaTimeProject[]
  bestDay: { date: string; seconds: number } | null
  range: { start: string; end: string }
}

Sources: lib/types.ts:39-48

Conclusion

The API Endpoints represent the data backbone of the pcstyledev portfolio. By abstracting external service complexities into a unified, cached, and edge-optimized interface, the system ensures high performance and reliability for real-time metrics. The architecture prioritizes data integrity through strict type definitions and robust error handling during external fetch operations.