backend-api

Backend API Guidelines

The Kaneo API is built with Hono, Drizzle ORM, PostgreSQL, and Better Auth. This document outlines conventions and patterns for backend development.

Framework: Hono

Hono is a lightweight web framework. Follow these patterns:

Route Structure

Routes are organized by feature in apps/api/src/:

// apps/api/src/task/index.ts
import { Hono } from "hono";
import { describeRoute, resolver, validator } from "hono-openapi";
import * as v from "valibot";
import createTask from "./controllers/create-task";
import getTask from "./controllers/get-task";

const task = new Hono<{
  Variables: {
    userId: string;
  };
}>()
  .get(
    "/:id",
    describeRoute({
      operationId: "getTask",
      tags: ["Tasks"],
      description: "Get a specific task by ID",
      responses: {
        200: {
          description: "Task details",
          content: {
            "application/json": { schema: resolver(taskSchema) },
          },
        },
      },
    }),
    validator("param", v.object({ id: v.string() })),
    async (c) => {
      const { id } = c.req.valid("param");
      const task = await getTask(id);
      return c.json(task);
    },
  );

export default task;

Best Practices

1. Always use OpenAPI decorators: Use describeRoute for all endpoints
2. Validate inputs: Use validator with Valibot schemas
3. Extract controllers: Keep route handlers thin, move logic to controller files
4. Type safety: Use Hono's type system for context variables

// Good: Thin route handler
.get("/:id", validator("param", v.object({ id: v.string() })), async (c) => {
  const { id } = c.req.valid("param");
  const task = await getTask(id);
  return c.json(task);
})

// Bad: Business logic in route handler
.get("/:id", async (c) => {
  const id = c.req.param("id");
  const task = await db.select().from(taskTable).where(eq(taskTable.id, id));
  // ... more logic
  return c.json(task);
})

Database: Drizzle ORM