Hono API Router Design

Relevant source files

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

• apps/server/src/index.ts
• apps/server/src/routes/router.ts
• apps/server/src/routes/v1/datasets.ts
• apps/server/src/routes/v1/upload.ts
• apps/server/src/routes/v1/chat.ts
• apps/server/src/routes/v1/discover.ts

Introduction

The Poneglyph backend leverages the Hono web framework to provide a lightweight, performant, and type-safe API routing architecture. The design follows a modular "sub-app" pattern where specific domains (chat, datasets, uploads, etc.) are encapsulated into individual router files and then composed into a central API router.

This architecture integrates middleware for logging, CORS, and authentication, ensuring that internal humanitarian data and research insights are handled securely. The use of @hono/zod-validator throughout the routing layer ensures that all incoming requests—whether from query parameters, JSON bodies, or multipart forms—are strictly validated against predefined schemas before reaching the business logic.

Sources: apps/server/src/index.ts:1-77, apps/server/src/routes/router.ts:1-15

Core Architecture and Entry Point

The application entry point initializes the main Hono instance and configures global middleware. A key aspect of the design is the separation of "direct routes" (like health checks and auth handlers) from the protected API sub-application.

Main App Configuration

The main instance handles:

• Global Logging: Uses honoLogger with custom categories and skip logic for health endpoints.
• CORS Configuration: Specifically configured for /api/auth/* and generic /api/* paths to allow frontend communication from specified origins.
• Error Handling: Implements app.onError for catching unhandled exceptions and app.notFound for standard 404 responses.

Sources: apps/server/src/index.ts:11-40, apps/server/src/index.ts:57-64

Request Flow Diagram

The following diagram illustrates how a request traverses from the entry point through middleware to specific route handlers.

Routing Structure and Composition

The Poneglyph API uses a hierarchical routing structure. A central apiRouter acts as a hub, mounting various versioned or domain-specific routers.

Router Path	Purpose	Key Functionality
/datasets	Dataset Management	Full-text search, filtering, and file proxying.
/chat	Agentic Research	Multi-agent UI streaming for humanitarian insights.
/upload	Data Ingestion	Parallel S3 uploads and background job queuing.
/discover	Community/Volunteers	Paginated volunteer listing and profile retrieval.

Sources: apps/server/src/routes/router.ts:7-13, apps/server/src/routes/v1/datasets.ts:51, apps/server/src/routes/v1/chat.ts:45, apps/server/src/routes/v1/upload.ts:49

Domain-Specific Router Implementation

Dataset Router (/v1/datasets)

The dataset router manages complex queries including PostgreSQL full-text search (FTS) and batch-fetching of tags. It includes a specialized file proxy route to handle both external URLs and R2 (S3-compatible) storage keys transparently.

• FTS Integration: Uses ts_rank and websearch_to_tsquery for ranking results.
• File Proxy: A dedicated route /:id/files/:index provides redirects to presigned S3 URLs or external sources while incrementing download counts.

Sources: apps/server/src/routes/v1/datasets.ts:70-75, apps/server/src/routes/v1/datasets.ts:211-255

Upload Router (/v1/upload)

The upload system uses a multi-stage process involving S3 uploads and internal callbacks.

Chat and Research Router (/v1/chat)

This router facilitates real-time interaction with the "Orchestrator Agent." It uses the ai SDK to create streaming responses.

• Middleware: Requires authentication via requireAuth.
• Streaming: Returns an AgentUIStreamResponse based on user messages.

Sources: apps/server/src/routes/v1/chat.ts:45-66

Validation and Type Safety

The design relies heavily on @hono/zod-validator to bridge the gap between runtime request data and TypeScript types. This ensures that route handlers receive strictly typed valid objects.

// Example from v1/upload.ts
uploadRouter.post("/", 
  requireAuth, 
  zValidator("form", UploadRequestSchema), 
  async (c) => {
    const { title, files } = c.req.valid("form");
    // title and files are now typed based on UploadRequestSchema
  }
);

Sources: apps/server/src/routes/v1/upload.ts:49-53, apps/server/src/routes/v1/datasets.ts:60

Conclusion

The Hono API Router Design in Poneglyph provides a highly organized and scalable foundation for humanitarian data analysis. By utilizing a composed router pattern, strict Zod validation, and specialized sub-apps for complex tasks like file proxying and agentic streaming, the system maintains high performance while ensuring technical clarity for developers.