# How to Navigate the Kaneo Monorepo Structure: A Complete Guide

> Master the kaneo monorepo structure with this guide. Learn to navigate apps, packages, and charts for efficient development and deployment in the usekaneo/kaneo repository.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Kaneo is organized as a pnpm monorepo managed by TurboRepo, divided into three top-level directories—`apps/` for runnable applications, `packages/` for shared libraries, and `charts/` for Kubernetes deployments—enabling efficient cross-package development and streamlined deployment workflows.**

The [usekaneo/kaneo](https://github.com/usekaneo/kaneo) repository follows a modern monorepo architecture designed to separate concerns between backend services, frontend interfaces, and infrastructure configuration. Understanding how to navigate the kaneo monorepo structure allows developers to quickly locate business logic, database schemas, and UI components without getting lost in nested directories. This guide breaks down the directory layout, coding patterns, and key files you need to know to contribute effectively.

## Top-Level Architecture

The repository root defines the workspace in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml), which lists all packages and enables pnpm to resolve dependencies across the entire tree. The monorepo is partitioned into three distinct sections:

- **`apps/`** – Contains three runnable applications: the **api** (Hono backend), **web** (React frontend), and **docs** (Next.js documentation site).
- **`packages/`** – Houses shared libraries including email utilities, generic helper libraries, and centralized TypeScript configuration.
- **`charts/`** – Stores Helm charts for deploying the application stack on Kubernetes.

This separation ensures that backend engineers can work on API routes without navigating frontend React components, while DevOps teams can manage Kubernetes manifests independently of application code.

## Backend Structure (apps/api)

The backend application follows a **feature-based organization** pattern that colocates related route handlers, controllers, and database logic.

### Feature-Based Organization

Each domain feature resides in its own directory under `apps/api/src/<feature>/`. The entry point [`index.ts`](https://github.com/usekaneo/kaneo/blob/main/index.ts) defines HTTP endpoints using Hono and OpenAPI decorators, while business logic is extracted to a `controllers/` subdirectory. For example, a typical feature module exports routes like this:

```typescript
// apps/api/src/<feature>/index.ts
import { Hono } from "hono";
import { describeRoute, validator } from "hono-openapi";
import * as v from "valibot";
import getItem from "./controllers/get-item";

const feature = new Hono<{ Variables: { userId: string } }>()
  .get("/:id",
    describeRoute({ operationId: "getItem", tags: ["Feature"], description: "Get item by ID" }),
    validator("param", v.object({ id: v.string() })),
    async (c) => {
      const { id } = c.req.valid("param");
      const item = await getItem(id);
      return c.json(item);
    }
  );

```

This pattern keeps route definitions declarative and delegates data access to controller functions.

### Database Schema Centralization

All database tables are declared in a single source of truth at [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts), which uses Drizzle ORM to define PostgreSQL schemas. Table relationships are configured separately in [`apps/api/src/database/relations.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/relations.ts), linking entities such as `user`, `session`, and `workspace`. For instance, the `task` table definition begins at line 63 of the schema file, making it easy to locate specific table structures without searching through multiple files.

## Frontend Structure (apps/web)

The `apps/web/` directory mirrors the backend's organizational clarity but adapts it for a React SPA built with Vite, TanStack Router, and Tailwind CSS v4.

### File-Based Routing

Routes follow a file-based convention under `apps/web/src/routes/`, where each folder corresponds to a URL segment. This eliminates the need for a central routing configuration file; the file system itself defines the navigation structure.

### Data Fetching Patterns

Data flow is managed through TanStack Query hooks segregated by operation type. Read operations live in `apps/web/src/hooks/queries/`, while write operations reside in `apps/web/src/hooks/mutations/`. Low-level API calls are abstracted into fetcher functions located in `apps/web/src/fetchers/<feature>/`. A typical query hook implementation looks like this:

```typescript
// apps/web/src/hooks/queries/<feature>/use-item.ts
import { useQuery } from "@tanstack/react-query";
import { getItem } from "@/fetchers/<feature>/get-item";

export function useItem(itemId: string) {
  return useQuery({
    queryKey: ["item", itemId],
    queryFn: () => getItem(itemId),
  });
}

```

Reusable UI components are stored in `apps/web/src/components/`, separate from route-specific logic and data fetching code.

## Shared Packages (packages/)

Common utilities that must be imported by multiple applications live in the `packages/` directory. Key packages include:

- **`packages/email/`** – Email sending helpers and template definitions.
- **`packages/libs/`** – Core shared logic, type definitions, and platform-agnostic utilities.
- **`packages/typescript-config/`** – Centralized [`tsconfig.json`](https://github.com/usekaneo/kaneo/blob/main/tsconfig.json) files referenced by all workspaces to ensure consistent compiler options.

These packages are treated as internal dependencies, allowing the API and web apps to import shared code using standard package names rather than relative paths.

## Kubernetes Deployment (charts/)

Infrastructure configuration is stored under `charts/kaneo/`, which contains Helm charts for production deployments. The [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml) file within this directory defines configurable parameters including image tags, resource limits, and ingress settings, enabling consistent deployment across different environments without modifying application source code.

## Navigation Strategies

To efficiently locate code within the kaneo monorepo structure, follow these systematic approaches:

1. **Open the workspace root** – Load the repository root in your IDE; the [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) file enables automatic resolution of cross-package imports and IntelliSense across the entire monorepo.

2. **Find backend features** – Search within `apps/api/src/` for the feature name. Look for an [`index.ts`](https://github.com/usekaneo/kaneo/blob/main/index.ts) file containing Hono route definitions and an adjacent `controllers/` folder containing business logic.

3. **Locate database tables** – Reference [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) for all table definitions. Use [`apps/api/src/database/relations.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/relations.ts) to understand foreign key relationships between entities.

4. **Trace frontend data flow** – Start from the route file in `apps/web/src/routes/`, then follow imports to the corresponding fetcher in `apps/web/src/fetchers/` and the consuming hook in `apps/web/src/hooks/queries/` or `hooks/mutations/`.

5. **Identify shared utilities** – Check `packages/libs/` or `packages/email/` before writing new helper functions to avoid duplication of existing logic.

## Summary

- Kaneo uses a **pnpm monorepo** managed by TurboRepo, defined by the root [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) file.
- The `apps/` directory contains three distinct applications: **api** (Hono backend), **web** (React frontend), and **docs** (Next.js site).
- Backend code follows a **feature-based pattern** with routes in `apps/api/src/<feature>/index.ts` and controllers in `controllers/` subdirectories.
- All database schemas are centralized in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts), with relations defined in [`relations.ts`](https://github.com/usekaneo/kaneo/blob/main/relations.ts).
- Frontend routing is file-based under `apps/web/src/routes/`, with data fetching abstracted through TanStack Query hooks in `hooks/queries/` and `hooks/mutations/`.
- Shared libraries reside in `packages/`, while Kubernetes deployment configurations are stored in `charts/kaneo/`.

## Frequently Asked Questions

### Where are the database table definitions located in the Kaneo monorepo?

All database table definitions are centralized in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). This file uses Drizzle ORM to declare PostgreSQL tables, while foreign key relationships and entity connections are configured separately in [`apps/api/src/database/relations.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/relations.ts).

### How do I add a new API endpoint to the Kaneo backend?

Create a new folder under `apps/api/src/` named after your feature. Inside, add an [`index.ts`](https://github.com/usekaneo/kaneo/blob/main/index.ts) file to define Hono routes using `describeRoute` and OpenAPI decorators, then implement the business logic in a `controllers/` subdirectory. Import and mount this feature in the main application entry point.

### What is the purpose of the packages directory in Kaneo?

The `packages/` directory contains shared libraries used by multiple applications in the monorepo. This includes `packages/email/` for sending notifications, `packages/libs/` for common utilities and types, and `packages/typescript-config/` for shared compiler configurations, ensuring consistency across the workspace.

### How does the frontend handle data fetching in the Kaneo monorepo?

The frontend uses TanStack Query for state management. Low-level API calls are defined in `apps/web/src/fetchers/<feature>/`, then consumed by custom hooks located in `apps/web/src/hooks/queries/` for read operations and `apps/web/src/hooks/mutations/` for write operations, keeping components decoupled from direct network logic.