Architecture Overview

Relevant source files

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

• src/index.ts
• src/server.ts
• src/handlers/admin.ts
• src/admin-html.ts
• README.md
• package.json
• SECURITY.md
• CONTRIBUTING.md

Gr8hopper is a lightweight, performance-focused URL redirect service built on the Hono web framework. Its architecture is designed for flexibility, supporting two primary deployment models: a serverless-first approach on Cloudflare Workers for edge performance, and a traditional server-based model using Node.js for VPS or containerized environments like Docker. This dual-platform support is a core architectural principle, achieved through a shared codebase with distinct entry points and a storage abstraction layer.

The system is split into two main functional areas: the public-facing redirect handler, which processes incoming requests and performs template-based URL rewriting, and a private admin interface for managing redirect routes and global settings. The admin interface is a self-contained single-page application embedded directly into the server binary, minimizing external dependencies and simplifying deployment.

Sources: README.md:9-12, CONTRIBUTING.md:43-48, package.json:39-40

Core Components

The application is built around the Hono framework, chosen for its minimal footprint and zero-dependency nature, making it ideal for both edge and server environments.

Sources: README.md:30, package.json:39

Key Dependencies

Dependency	Version	Description
hono	^4.6.0	The core web framework used for routing and request handling.
@hono/node-server	^1.13.0	Adapter for running Hono applications on Node.js.
typescript	^5.7.0	The language used for the entire codebase.
wrangler	^4.58.0	The command-line tool for developing and deploying Cloudflare Workers.

Sources: package.json:39-40, 44, 49

Project Structure

The project is organized to separate concerns between platform-specific entry points, shared handlers, and storage adapters.

src/
├── index.ts           # Cloudflare Workers entry point
├── server.ts          # Node.js/Bun entry point
├── admin-html.ts      # Embedded HTML/JS for the Admin UI
├── handlers/
│   ├── redirect.ts    # Core redirect logic
│   └── admin.ts       # Admin API endpoints
├── storage/
│   ├── adapter.ts     # Storage interface definition
│   ├── kv.ts          # Cloudflare KV adapter
│   └── json-file.ts   # JSON file adapter (for Node.js)
└── middleware/
    └── auth.ts        # Basic authentication middleware

Sources: CONTRIBUTING.md:42-50, README.md:254-269

Deployment Models

Gr8hopper's architecture supports two distinct deployment environments, sharing the same core application logic but using different entry points and storage backends.

This diagram illustrates the two deployment models and their components.

Cloudflare Workers

This is the recommended model for production due to its performance and low cost.

• Entry Point: src/index.ts
• Storage: Uses the KVAdapter to store routes and settings in Cloudflare KV, a globally distributed key-value store.
• Initialization: Handlers and configuration are initialized on the first request to a worker instance (cold start) and then cached for subsequent requests.
• Configuration: Managed via environment variables and secrets set using the wrangler CLI (e.g., ADMIN_USERNAME, CLOUDFLARE_ZONE_ID).

Sources: src/index.ts:15-30, README.md:273-274

Node.js / VPS

This model is for self-hosting on a virtual private server, Docker container, or local machine.

• Entry Point: src/server.ts
• Storage: Uses the JsonFileAdapter to store routes and settings in a local JSON file (e.g., routes.json).
• Server: Uses @hono/node-server to run the Hono application as a standard Node.js HTTP server.
• Configuration: Managed via standard environment variables (e.g., PORT, CONFIG_FILE, ADMIN_USERNAME). The server will read a .dev.vars file for development convenience if NODE_ENV is not production.

Sources: src/server.ts:10-15, 83-84, 131-132

Request Flow

Redirect Flow

The primary function of the service is to handle redirects. The flow is optimized for performance by leveraging aggressive caching.

This sequence diagram shows the steps involved in a redirect request.

Admin Flow

The admin interface is a protected area for managing the service. All access is controlled by HTTP Basic Authentication.

• Authentication: The basicAuth middleware is applied to all routes under the configured ADMIN_PATH. It checks for ADMIN_USERNAME and ADMIN_PASSWORD from the environment.
• UI Serving: The admin panel is a single HTML file with embedded CSS and JavaScript, generated by the getAdminHtml function. This avoids the need for a separate front-end build process or static file hosting.
• API: A RESTful API is exposed under the admin path for CRUD operations on routes and settings.

This sequence diagram illustrates an admin making a change via the API.

Admin API

The admin API provides endpoints for managing routes and settings. It is mounted under the path defined by the ADMIN_PATH environment variable (default: /admin).

Sources: src/handlers/admin.ts, README.md:213-224

Method	Endpoint	Description	Source File
GET	/routes	List all routes.	src/handlers/admin.ts:76-84
GET	/routes/:id	Get a single route by its ID.	src/handlers/admin.ts:87-107
POST	/routes	Create a new route.	src/handlers/admin.ts:113-140
PATCH	/routes/:id	Partially update an existing route.	src/handlers/admin.ts:169-170
DELETE	/routes/:id	Delete a route.	src/handlers/admin.ts:188-203
GET	/settings	Get global settings.	src/handlers/admin.ts:206-214
PUT	/settings	Update global settings.	src/handlers/admin.ts:217-239
GET	/export	Export all routes and settings as a JSON file.	src/handlers/admin.ts:242-263
POST	/import	Import routes and settings from a JSON file, replacing all existing data.	src/handlers/admin.ts:266-368
GET	/purge-cache/status	Check if Cloudflare cache purging is configured and available.	src/handlers/admin.ts:371-375
POST	/purge-cache	Purge the entire Cloudflare CDN cache.	src/handlers/admin.ts:378-406

Configuration

Configuration is managed primarily through environment variables, which differ slightly between the two deployment models.

Environment Variables

Variable	Default	Platform	Description
PORT	3000	VPS	HTTP server port.
CONFIG_FILE	./routes.json	VPS	Path to the JSON file for storing routes.
ADMIN_USERNAME	(required)	Both	Admin panel username. Must not be 'admin'.
ADMIN_PASSWORD	(required)	Both	Admin panel password.
ADMIN_PATH	admin	Both	The URL path for the admin interface.
CLOUDFLARE_API_TOKEN	(optional)	Cloudflare	API token for purging the CDN cache.
CLOUDFLARE_ZONE_ID	(optional)	Cloudflare	Zone ID for purging the CDN cache.

Sources: README.md:195-202, src/server.ts:83-86, 120-129, src/index.ts:37-51, 57-59, SECURITY.md:16-18

Conclusion

The architecture of gr8hopper is a deliberate balance of simplicity, performance, and portability. By using Hono as a lightweight core and abstracting platform-specific details like storage, it successfully provides a consistent feature set across both serverless edge and traditional server environments. The embedding of the admin UI and the use of environment variables for configuration make the application self-contained and easy to deploy and manage, fulfilling its goal of being a "lightweight, performance-first URL redirect service."

Sources: README.md:9