API Middlewares & Route Helpers
Relevant source files
The following files were used as context for generating this wiki page:
The Poneglyph backend, built on the Hono framework and Bun runtime, utilizes a modular middleware architecture to handle cross-cutting concerns such as logging, security (CORS), and authentication. These middlewares ensure that requests are properly validated and authorized before reaching core business logic, such as dataset uploads or research queries.
Route helpers and utilities, including specialized loggers and file-type mappers, streamline the development of API endpoints. These components work together to provide a robust execution environment for the server's primary functions, which include managing humanitarian datasets and facilitating AI-powered research.
Sources: apps/server/src/index.ts:1-15, README.md:1-15
Middleware Architecture
The server application initializes several global and route-specific middlewares to process incoming HTTP traffic. The execution order follows the standard Hono middleware stack, starting with logging and moving into security and authentication.
Core Middlewares
| Middleware | Scope | Purpose |
|---|---|---|
honoLogger | Global | Provides structured request logging for all paths except /health. |
cors | /api/auth/* | Configures Cross-Origin Resource Sharing specifically for authentication routes. |
cors | /api/* | General CORS configuration for the main API endpoints. |
authMiddleware | /api/* | Validates session or token authenticity for all API sub-routes. |
Sources: apps/server/src/index.ts:12-52
Request Lifecycle Flow
The following diagram illustrates how a request passes through the middleware layers before reaching a route handler.
The request flow ensures that telemetry is captured first, followed by origin validation, and finally identity verification for protected resources.
Sources: apps/server/src/index.ts:12-55
Authentication and Security Helpers
Poneglyph integrates Better-Auth for identity management. The middleware implementation ensures that sensitive operations, such as file uploads, are restricted to authenticated users.
Restricted Route Access
Routes requiring user context use the requireAuth helper. This middleware extracts user information from the request context and makes it available to the subsequent handler. For example, in the upload process, the userId is retrieved directly from the authorized user object.
uploadRouter.post("/", requireAuth, zValidator("form", UploadRequestSchema), async (c) => {
const user = c.get("user")!;
const userId = user.id;
// ... processing logic
});
Sources: apps/server/src/routes/v1/upload.ts:40-45
Route Helpers and Data Mapping
To maintain consistency across API versions, the project employs route helpers that manage data transformations and validation.
MIME Type Mapping
A specific helper object, MIME_TO_EXT, is used within the upload routes to map incoming file types to supported extensions for S3 storage and database indexing.
| MIME Type | Extension |
|---|---|
application/pdf | |
text/csv | csv |
application/json | json |
image/webp | webp |
Sources: apps/server/src/routes/v1/upload.ts:16-29
Logging Utility
The project uses a structured logging system through @logtape/logtape. A logger.getChild helper is used to create scoped loggers for specific modules, such as "upload", which allows for more granular log filtering and debugging.
const log = logger.getChild("upload");
// Usage: log.info("Upload received", { uploadId });
Sources: apps/server/src/routes/v1/upload.ts:12-14, apps/server/package.json:20-21
API Validation Strategy
Middlewares are also used for schema validation via @hono/zod-validator. This ensures that any data entering the system via POST requests conforms to defined Zod schemas before any business logic is executed.
Conclusion
The API Middlewares and Route Helpers in Poneglyph provide a standardized foundation for building secure and observable humanitarian data services. By centralizing logic for authentication, CORS, and logging into reusable middleware components, the architecture maintains a clean separation of concerns and simplifies the implementation of complex features like agentic research and dataset processing.
Sources: apps/server/src/index.ts:60-75, README.md:5-15