Hono API Implementation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Hono API implementation serves as the backend layer for the pcstyledev portfolio, providing a lightweight, high-performance interface for retrieving project metadata and real-time developer statistics. Built with the Hono framework and optimized for the Vercel Edge Runtime, it aggregates data from local JSON storage, the WakaTime API, and the GitHub GraphQL/REST APIs.
Sources: api/index.ts:1-20, package.json:13
This API acts as a proxy and data aggregator, transforming raw metrics from external providers into structured formats consumed by the frontend components. It includes robust features such as in-memory caching, inflight request tracking, and environment-based health monitoring to ensure reliability across the portfolio's stats dashboards.
Sources: api/index.ts:47-60, hooks/useWakaTime.ts:25-30
Core Architecture
Edge Runtime and Framework
The API is built using hono and deployed via @vercel/edge. The entry point initializes a Hono instance with a base path of /api and exports a Vercel handler.
The diagram shows the request flow through global middlewares before reaching specific route groups.
Sources: api/index.ts:1-35, api/index.ts:98-105
Middleware and Utility Layers
The implementation utilizes several middleware layers for cross-cutting concerns:
- Global Logger: Generates unique request IDs and logs the method, path, status, and duration of every request.
- CORS: Enables cross-origin resource sharing for frontend consumption.
- Credential Guards: Route-specific middleware that validates the existence of
WAKATIME_API_KEY,GITHUB_TOKEN, andGITHUB_USERNAMEbefore processing sensitive requests.
Sources: api/index.ts:38-51, api/index.ts:108-120
Data Management and Fetching
Caching Strategy
The API implements a custom in-memory cache to minimize external API calls and respect rate limits. It distinguishes between standard TTL (60s) and GitHub-specific TTL (300s).
| Feature | Implementation Detail |
|---|---|
| Cache Store | Map<string, { data: unknown; expires: number }> |
| Inflight Tracker | Map<string, Promise<any>> to prevent redundant simultaneous fetches |
| Default TTL | 60,000 ms (1 minute) |
| GitHub TTL | 300,000 ms (5 minutes) |
| Timeout | 10,000 ms fetch timeout |
Sources: api/index.ts:53-65
Robust Fetching
The fetchWithRetry utility (despite the name, primarily a deduplicating fetcher) handles Edge-compatible requests with timeouts and AbortController signals. It clones responses to allow multiple consumers and prevents "Request body already read" errors.
Sources: api/index.ts:74-101
API Endpoints
Project Metadata
The API serves project data from a static JSON file, acting as the single source of truth for the portfolio's artifact nodes.
GET /api/projects: Returns the full list of project objects.GET /api/projects/:id: Returns a specific project by its slug.GET /api/projects/meta: Provides the total count and thelastUpdatedtimestamp from the data source.
Sources: api/index.ts:122-143, data/projects/projects.json
WakaTime Integration
Aggregates coding activity from the last 7 days. It parses raw data into WakaTimeSummary and WakaTimeStatus types.
This sequence illustrates the aggregation logic where multiple days of WakaTime data are summed into a single summary.
Sources: api/index.ts:146-210, lib/types.ts:37-64
GitHub Integration
Provides repository statistics and contribution data using both GraphQL (for calendars) and REST (for general stats and events).
/api/github/contributions: Fetches a contribution calendar using a GraphQL query./api/github/stats: Aggregates public repo counts, star counts, followers, and calculates the "Most Active Repo" based on recent PushEvents.
Sources: api/index.ts:246-340, lib/types.ts:73-100
Data Structures
The API uses TypeScript interfaces defined in lib/types.ts to ensure consistency between the backend responses and frontend hooks.
// Sources: [lib/types.ts:6-23]
export interface Project {
id: string
name: string
desc: string
stack: string[]
status: 'active' | 'maintenance' | 'experimental' | 'prototype' | 'disabled'
icon: string
updatedAt: string
}
// Sources: [lib/types.ts:88-100]
export interface GitHubStats {
publicRepos: number
totalStars: number
totalCommits?: number
lastCommit?: {
message: string
repo: string
date: string
url: string
}
}
Conclusion
The Hono API Implementation provides a centralized, performant data layer for the pcstyledev portfolio. By leveraging Edge Runtime and implementing custom caching and inflight request tracking, it ensures that high-latency external requests (GitHub/WakaTime) do not degrade the user experience of the portfolio. The structured routing and middleware guards provide a secure and scalable foundation for real-time system metrics.
Sources: api/index.ts:342-345, pages/Stats.tsx:140-150