# Kaneo Project Structure Explained: A Deep Dive into the usekaneo/kaneo Monorepo

> Explore the usekaneo/kaneo monorepo structure. Discover how apps, packages, and charts organize the backend API, frontend SPA, docs, shared libraries, and Kubernetes config.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: deep-dive
- Published: 2026-08-04

---

**The usekaneo/kaneo project is organized as a pnpm monorepo managed by TurboRepo, with three top-level directories (`apps/`, `packages/`, `charts/`) containing the backend API, frontend SPA, documentation site, shared libraries, and Kubernetes deployment configuration.**

Kaneo follows a modern **monorepo architecture** that consolidates all code, documentation, and deployment assets in a single repository. This structure, defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml), enables code sharing across applications while maintaining clear separation of concerns. Understanding the Kaneo project structure is essential for contributors and teams evaluating the codebase for self-hosted project management.

## The Three Core Directories

The repository root contains three primary directories that organize all functional code:

### apps/ — Runnable Applications

The `apps/` directory houses three distinct applications that form the complete Kaneo platform:

- **api** — Backend REST API built with **Hono**, **PostgreSQL** (via **Drizzle ORM**), and **Better Auth** for authentication
- **web** — Frontend single-page application using **React 19+**, **Vite**, **TanStack Router & Query**, **Tailwind CSS**, **Zustand**, and **Radix UI**
- **docs** — Public documentation site powered by **Next.js**

Each app is independently deployable yet shares configuration and types through the `packages/` workspace.

### packages/ — Shared Libraries

The `packages/` directory contains reusable modules consumed by multiple apps:

- **email** — Transactional email templates and sending utilities
- **libs** — Core **TypeScript utilities** imported by both API and web layers
- **typescript-config** — Reusable [`tsconfig.json`](https://github.com/usekaneo/kaneo/blob/main/tsconfig.json) presets ensuring consistent compilation across the workspace

This arrangement eliminates duplication and enforces type safety across API boundaries.

### charts/ — Kubernetes Deployment

The `charts/` directory includes a **Helm chart** (`charts/kaneo/`) that automates Kubernetes deployments. This enables production installations with configurable replicas, ingress rules, and secret management.

## Supporting Configuration Files

Beyond the three main directories, several root-level files govern workspace behavior:

| File | Purpose |
|------|---------|
| [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) | Declares workspace packages (`apps/**`, `packages/**`) and build-time dependencies |
| [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) | Specifies **pnpm** as the package manager via the `packageManager` field; requires **Node ≥ 18** |
| `.env` | Single source of truth for environment variables including `KANEO_CLIENT_URL`, `KANEO_API_URL`, `AUTH_SECRET`, and database connection strings |
| [`CLAUDE.md`](https://github.com/usekaneo/kaneo/blob/main/CLAUDE.md) | Comprehensive contributor guide documenting monorepo patterns and code conventions |
| [`README.md`](https://github.com/usekaneo/kaneo/blob/main/README.md) | Quick-start guide with Docker and Kubernetes instructions |
| [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) | Detailed variable reference for local and production configurations |

## Visual Directory Layout

As documented in [`CLAUDE.md`](https://github.com/usekaneo/kaneo/blob/main/CLAUDE.md), the complete structure appears as:

```

kaneo/
├── apps/
│   ├── api/          # Backend API (Hono, Drizzle, Better Auth)

│   ├── web/          # Frontend SPA (React 19, Vite, TanStack)

│   └── docs/         # Documentation site (Next.js)

├── packages/
│   ├── email/        # Email utilities

│   ├── libs/         # Shared TypeScript libraries

│   └── typescript-config/
└── charts/           # Kubernetes Helm charts

```

## Code Patterns Across the Monorepo

The Kaneo project structure enables consistent patterns for backend and frontend development.

### Backend Route Pattern (apps/api)

API routes follow a standardized Hono setup with OpenAPI documentation and Valibot validation:

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

export const example = new Hono()
  .get(
    "/:id",
    describeRoute({
      operationId: "getExample",
      tags: ["Example"],
      description: "Retrieve an example resource by its CUID2",
    }),
    validator("param", v.object({ id: v.string() })),
    async (c) => {
      const { id } = c.req.valid("param");
      const example = await getExample(id);
      return c.json(example);
    },
  );

```

This pattern appears throughout `apps/api/src/` with each domain receiving its own directory containing routes, controllers, and database queries.

### Frontend Integration Pattern (apps/web)

The web app consumes API endpoints through typed fetchers and TanStack Query hooks:

```typescript
// apps/web/src/fetchers/example/get-example.ts
import { api } from "@/lib/api-client";

export const getExample = async (id: string) => {
  const response = await api.get(`/example/${id}`);
  return response.json();
};

```

```typescript
// apps/web/src/hooks/queries/example/use-example.ts
import { useQuery } from "@tanstack/react-query";
import { getExample } from "@/fetchers/example/get-example";

export const useExample = (id: string) => {
  return useQuery(["example", id], () => getExample(id));
};

```

The `apps/web/src/routes/` directory implements **file-based routing** via TanStack Router, while `apps/web/src/components/` houses the UI library built on Radix primitives.

## Key Source Files to Know

| Path | Description |
|------|-------------|
| [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) | Central **Drizzle ORM schema** defining all tables, CUID2 primary keys, and timestamp handling |
| `apps/web/src/routes/` | File-based SPA route definitions |
| `apps/web/src/components/` | Radix-based component library with Tailwind styling |
| `packages/libs/` | Shared TypeScript utilities cross-imported by API and web |
| `charts/kaneo/` | Production Helm chart for Kubernetes deployment |

## Summary

- **Kaneo uses a pnpm monorepo** with TurboRepo orchestration, organizing code into `apps/`, `packages/`, and `charts/` directories
- **Three applications** live in `apps/`: the Hono-based API, the React/Vite frontend, and the Next.js documentation site
- **Shared code** resides in `packages/` for email, utilities, and TypeScript configuration
- **Single `.env` file** at the repository root supplies configuration to all applications
- **Helm chart included** at `charts/kaneo/` for streamlined Kubernetes deployments
- **Node 18+ and pnpm required** as specified in [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json)

## Frequently Asked Questions

### What package manager does Kaneo use?

Kaneo uses **pnpm** as its package manager, declared explicitly in the `packageManager` field of [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json). The workspace configuration in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) defines `apps/**` and `packages/**` as package globs. Node.js version 18 or higher is required.

### How do the frontend and backend share types?

Both applications import from the `packages/libs` workspace package, which contains shared **TypeScript utilities, types, and helper functions**. This ensures API payloads and responses remain type-safe across the network boundary without code duplication.

### Can I deploy Kaneo without Kubernetes?

Yes. While the `charts/` directory provides a **Helm chart for Kubernetes**, the [`README.md`](https://github.com/usekaneo/kaneo/blob/main/README.md) includes **Docker-based deployment instructions** using `docker-compose`. The monorepo structure supports multiple deployment targets from the same source.

### Where is the database schema defined?

All tables, relationships, and migration strategies 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 define the PostgreSQL schema with **CUID2 primary keys** and automatic timestamp handling.