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

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, 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 — 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:

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:

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.

apps/site/ — Marketing Website

Static marketing pages that power the product landing site at 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.

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

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 — 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 — 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 — English (US) strings
• Additional locale files for multi-language support

---

Navigation Files

Two critical files sit at the repository root:

File	Purpose
README.md	Project introduction, quick-start guide, and contribution guidelines
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 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 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.

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