Kaneo API Request Lifecycle: From HTTP Request to Real-Time Broadcast

An inbound API request in Kaneo traverses a Hono-based pipeline that includes OpenAPI route registration, authentication middleware, Zod schema validation, controller execution with Drizzle ORM transactions, event publishing, and WebSocket broadcasting before returning a typed JSON response.

Kaneo is an open-source project management platform built on the Hono framework. Understanding the request lifecycle for an API call in Kaneo is essential for developers extending the backend or debugging authentication workflows. Every HTTP request follows a predictable path through middleware chains, database operations, and real-time event propagation as implemented in the apps/api/src directory.

Route Registration with createRoute

All API endpoints are declared using the createRoute helper exported from apps/api/src/openapi.ts. This utility, provided by @hono/zod-openapi, registers the HTTP method, URL path, request/response Zod schemas, and attaches route-specific metadata for OpenAPI documentation generation.

Individual feature modules, such as apps/api/src/task/index.ts, import createRoute to define their specific endpoints. The centralized apiRouter instance in openapi.ts aggregates these routes and configures the global middleware pipeline, validation hooks, and the jsonResponse helper used for consistent response formatting.

The Pre-Validation Middleware Pipeline

Before Zod schema validation executes, the request passes through a configurable chain of Hono middleware functions. This pre-validation stage handles security, identity resolution, and access control using raw request headers and cookies.

Authentication and Identity Resolution

The primary authentication layer resides in apps/api/src/utils/authenticate-api-request.ts. This middleware inspects the incoming request for a valid session cookie or API key header, verifies the credentials against the database, and populates the Hono context variables—including c.get("userId")—for downstream handlers. If authentication fails, the middleware throws an HTTPException with an appropriate 401 status code.

API Key Verification

For requests using API key authentication, the system invokes apps/api/src/utils/verify-api-key.ts. This module validates the key's signature, checks expiration dates, and enforces key-specific permissions before allowing the request to proceed to workspace-level authorization.

Workspace Access Control

The apps/api/src/utils/workspace-access-middleware.ts middleware validates that the authenticated user has membership in the workspace referenced by the URL parameter (e.g., /api/v1/workspaces/:workspaceId). This ensures that project-scoped resources remain isolated between different organizations.

Bot Protection

When enabled, the pipeline includes apps/api/src/utils/verify-turnstile.ts to validate Cloudflare Turnstile captcha tokens. This middleware runs early in the chain to mitigate automated abuse against public endpoints such as user registration or login.

Schema Validation and Route Handling

After the middleware chain completes, Hono's validation hook—configured in the apiRouter within openapi.ts—executes the Zod schemas defined during route registration. If the request body, query parameters, or path variables fail validation, the framework automatically throws an HTTPException(400) with a detailed error message, preventing invalid data from reaching the controller layer.

Controller Execution and Database Operations

Once validation passes, the request enters the route's controller function, typically located in apps/api/src/**/controllers/. For example, apps/api/src/workspace/controllers/get-workspace-members.ts implements the domain logic for fetching workspace membership data. Controllers interact with PostgreSQL through the Drizzle ORM, utilizing the schema definitions exported from apps/api/src/database/schema.ts.

Controllers handle database transactions using typed queries such as db.select(), db.insert(), or db.update(). They may also call utility functions, apply business rules, and prepare the response payload before handing it to the response formatter.

Event Publishing and Real-Time Broadcast

For mutating operations (create, update, delete), controllers trigger side effects by calling publishEvent() from apps/api/src/mcp/tools.ts. This function emits domain events—such as task.created or workspace.member.added—that are consumed by the WebSocket layer.

The broadcast system, implemented in apps/api/src/ws/in-memory-broadcast-adapter.ts (or redis-broadcast-adapter.ts when Redis is configured), listens for these events and pushes updates to connected clients. This ensures that frontend applications receive real-time updates without requiring manual cache invalidation.

Response Serialization and Completion

Controllers return data using the jsonResponse helper defined in apps/api/src/openapi.ts. This utility wraps the payload with OpenAPI metadata, serializes the response body to JSON, and sets the correct Content-Type header. After the handler finishes, any configured after hooks execute for logging or metrics collection before Hono streams the final HTTP response back to the client.

Summary

• Route Registration: Endpoints are defined using createRoute in apps/api/src/openapi.ts with Zod schemas for type safety.
• Pre-Validation Middleware: authenticate-api-request.ts resolves identity, verify-api-key.ts validates keys, and workspace-access-middleware.ts enforces workspace permissions.
• Schema Validation: Hono validates requests against Zod definitions immediately after middleware execution.
• Controller Logic: Domain handlers in apps/api/src/**/controllers/ execute business logic using Drizzle ORM against apps/api/src/database/schema.ts.
• Real-Time Events: Mutations call publishEvent() from apps/api/src/mcp/tools.ts to trigger WebSocket broadcasts via adapters in apps/api/src/ws/.
• Response Handling: jsonResponse from openapi.ts formats the final JSON payload with OpenAPI metadata.

Frequently Asked Questions

What middleware runs before request validation in Kaneo?

The pre-validation middleware chain includes authenticate-api-request.ts for session/API key verification, verify-api-key.ts for key-specific permissions, workspace-access-middleware.ts for workspace membership checks, and optionally verify-turnstile.ts for bot protection. These execute sequentially in the Hono pipeline before Zod validation occurs.

How does Kaneo handle real-time updates after a database mutation?

After a controller commits changes to the database using Drizzle ORM, it calls publishEvent() from apps/api/src/mcp/tools.ts. This emits a domain event that the WebSocket broadcast adapter—either in-memory-broadcast-adapter.ts or redis-broadcast-adapter.ts—pushes to connected clients, ensuring UI synchronization across all active sessions.

Which file defines the OpenAPI route helpers in Kaneo?

The apps/api/src/openapi.ts file exports the createRoute helper for registering endpoints, the jsonResponse utility for response formatting, and the centralized apiRouter instance that configures global middleware and validation hooks for the Hono application.

Where is the authentication logic implemented in the Kaneo API?

Authentication logic is centralized in apps/api/src/utils/authenticate-api-request.ts, which verifies session cookies or API key headers and populates the request context with user identity. Supplementary verification for API keys specifically occurs in apps/api/src/utils/verify-api-key.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}