# Key Directories in the usekaneo/kaneo Repository: A Complete Structural Guide

> Explore the key directories in the usekaneo/kaneo repository. Understand the monorepo structure, application folders, shared packages, and deployment assets for efficient development.

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

---

**The usekaneo/kaneo repository follows a pnpm workspaces monorepo pattern with four main application directories (`apps/web`, `apps/api`, `apps/docs`, `apps/site`), shared packages, Helm charts for Kubernetes deployment, and dedicated test suites.**

Kaneo is an open-source project management platform built with modern full-stack TypeScript. Understanding the directory structure is essential for contributors, operators, and anyone extending the platform. This guide maps each key directory to its purpose and shows how the codebase is organized.

---

## The `apps/` Directory: Runnable Applications

The `apps/` folder contains all deployable services. Each subdirectory is an independent application with its own [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json), build configuration, and entry points.

### `apps/web/` — React Frontend

The primary user interface built with **Vite**, **React**, **TanStack Router**, **TanStack Query**, **Zustand**, and **Radix UI**.

Key architectural patterns found in this directory:

- **[`apps/web/src/lib/auth-client.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/lib/auth-client.ts)** — Client-side authentication wrapper that interfaces with the Better-Auth system
- **`apps/web/src/fetchers/`** — Data fetching utilities used with TanStack Query
- **`apps/web/src/components/`** — Reusable UI components built on Radix UI primitives

Example task fetcher hook:

```typescript
import { useQuery } from "@tanstack/react-query";
import { getTask } from "@/fetchers/task";

export function useTask(taskId: string) {
  return useQuery(["task", taskId], () => getTask(taskId));
}

```

### `apps/api/` — Hono Backend Service

The REST API server built with **Hono**, **Drizzle ORM**, **Better-Auth**, and **Valibot** for request validation. While the full file listing wasn't cached in the source analysis, the project documentation confirms this directory contains:

- OpenAPI-documented route handlers
- Database schema definitions
- Authentication controllers

Example API route structure:

```typescript
import { Hono } from "hono";
import { validator } from "hono-openapi";
import * as v from "valibot";
import { getTask } from "./controllers/get-task";

const api = new Hono()
  .get(
    "/tasks/: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);
    },
  );

```

### `apps/docs/` — Documentation Site

A **Next.js** application that publishes the public documentation for Kaneo. Lives at [kaneo.app/docs](https://kaneo.app/docs).

### `apps/site/` — Marketing Website

Static marketing pages that power the product landing site at [kaneo.app](https://kaneo.app).

---

## The `packages/` Directory: Shared Libraries

Reusable code consumed by multiple applications in the monorepo. Typical contents include:

| Package | Purpose |
|---------|---------|
| `packages/typescript-config/` | Shared TypeScript configurations that all workspaces extend |
| Utility libraries | Common helpers for date formatting, validation, etc. |
| Type definitions | Shared interfaces used across frontend and backend |

Example shared configuration at **[`packages/typescript-config/base.json`](https://github.com/usekaneo/kaneo/blob/main/packages/typescript-config/base.json)**.

Example shared utility for ID generation (used throughout the schema):

```typescript
import { createId } from "@paralleldrive/cuid2";

export function generateProjectId() {
  return createId(); // CUID2 – used as primary keys in database tables
}

```

---

## Infrastructure and Operations

### `charts/kaneo/` — Kubernetes Helm Chart

Production deployment configuration for running Kaneo on Kubernetes. Contains:

- **[`Chart.yaml`](https://github.com/usekaneo/kaneo/blob/main/Chart.yaml)** — Helm chart metadata
- Templates for services, deployments, ingress rules, and secrets

Reference this directory when deploying to self-hosted or cloud Kubernetes environments.

### `.github/` — CI/CD and Automation

GitHub Actions workflows, issue templates, and Dependabot configuration. Key files include:

- [`.github/workflows/ci.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/ci.yml) — Continuous integration pipeline
- Pull request templates and code ownership rules

---

## Supporting Directories

### `tests/` — Automated Test Suites

Comprehensive testing infrastructure including:

- `tests/api-integration/` — End-to-end API tests covering authentication, project management, task handling, and billing flows
- Unit test configurations for individual packages

Example integration test coverage for task endpoints.

### `scripts/` — Development Tooling

Helper scripts for maintenance tasks such as:

- Internationalization (i18n) string extraction and management

### `i18n/` — Translation Files

JSON translation files for every supported locale:

- [`i18n/en-US.json`](https://github.com/usekaneo/kaneo/blob/main/i18n/en-US.json) — English (US) strings
- Additional locale files for multi-language support

---

## Navigation Files

Two critical files sit at the repository root:

| File | Purpose |
|------|---------|
| [`README.md`](https://github.com/usekaneo/kaneo/blob/main/README.md) | Project introduction, quick-start guide, and contribution guidelines |
| [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) | Required environment variables and local development instructions |

---

## Summary

- **Monorepo structure**: pnpm workspaces with clear separation between `apps/` (runnable) and `packages/` (shared)
- **Four applications**: Web UI (`apps/web`), API server (`apps/api`), docs site (`apps/docs`), and marketing site (`apps/site`)
- **Backend stack**: Hono server with Drizzle ORM, Better-Auth, and Valibot validation
- **Frontend stack**: Vite + React with TanStack ecosystem and Radix UI
- **Deployment**: Helm charts in `charts/kaneo/` for Kubernetes
- **Quality**: Integration tests in `tests/` and shared configs in `packages/`

---

## Frequently Asked Questions

### What is the purpose of the `apps/api/` directory?

The `apps/api/` directory houses the backend REST API built with **Hono**. It contains OpenAPI-documented route handlers, **Drizzle ORM** database schemas, **Better-Auth** authentication logic, and **Valibot** request validators. This directory is essential for understanding how Kaneo serves data to the frontend.

### How does the `packages/` directory reduce code duplication?

The `packages/` directory stores shared libraries that multiple applications import. For example, [`packages/typescript-config/base.json`](https://github.com/usekaneo/kaneo/blob/main/packages/typescript-config/base.json) provides a single source of truth for TypeScript compiler options. Any changes to shared configurations propagate to all consuming apps, ensuring consistency across the monorepo.

### Where is the Kubernetes deployment configuration located?

Helm charts for Kubernetes deployment live in **`charts/kaneo/`**. This directory contains [`Chart.yaml`](https://github.com/usekaneo/kaneo/blob/main/Chart.yaml) and templates for services, deployments, and ingress resources. Use this directory when deploying Kaneo to production Kubernetes clusters.

### What testing strategy does Kaneo use?

Kaneo maintains automated tests in the **`tests/`** directory, with subdirectories for different test types. The `tests/api-integration/` folder contains end-to-end tests that verify authentication flows, project operations, task management, and billing logic against a running API instance.