kaneo 딥다이브
— "필요한 것만, 군더더기 없이" : 자가호스팅 칸반 뒤에 숨은 타입세이프 풀스택의 표본

1한 줄 정체

kaneo는 "내 서버(또는 내 노트북)에 도커로 직접 띄워 쓰는, 군더더기를 덜어낸 오픈소스 프로젝트 관리 도구"다. 팀이 할 일을 칸반 보드에 카드로 붙이고, 백로그에 쌓고, 담당자·마감일·라벨·댓글을 달고, 워크스페이스 단위로 사람을 초대해 함께 쓰는 — 그 익숙한 일을 한다. 다른 점은 두 가지다. 첫째, 데이터가 남의 클라우드가 아니라 내 서버에 있다(자가호스팅). 둘째, "기능을 더 넣기"가 아니라 "안 쓰는 기능을 빼기"를 제품 원칙으로 삼는다.

기술적으로 더 정확히 말하면, kaneo는 하나의 도커 이미지 안에 "React로 만든 웹 앱(프론트)"과 "Hono로 만든 API 서버(백)"를 함께 담아 5173 포트 하나로 서빙하고, 상태는 전부 PostgreSQL 한 곳에 저장하는 풀스택 웹 애플리케이션이다. 실시간 협업(누가 카드를 옮기면 다른 사람 화면도 즉시 갱신)은 WebSocket으로, 이미지 첨부는 S3로, 팀·권한은 인증 라이브러리로 처리한다. 이 모든 조각이 타입스크립트 하나로, 앞뒤가 타입으로 연결된 채 굴러간다는 게 이 레포의 진짜 정체다.

2왜 주목받는가 — 기능 경쟁이 아니라 "덜어내기"로

첫째, 포지셔닝이 선명하다. kaneo는 마케팅 사이트에 아예 /jira-alternative, /trello-alternative, /linear-alternative 비교 페이지를 두고, 세 거인의 약점을 정확히 겨냥한다 — Jira는 무겁고 배우기 어렵다, Trello는 백로그·워크플로우가 유료 확장에 묶여 있다, Linear는 폐쇄형·클라우드 전용이라 자가호스팅이 안 된다. kaneo는 "오픈소스 + 자가호스팅 + 덜어낸 UX"라는 빈틈을 노린다.

둘째, 기술 스택이 "지금 가장 트렌디한 조합"이다. React 19(React Compiler 포함)·Vite 7·TanStack Router/Query·Tailwind 4·Hono·Drizzle·better-auth·Valibot — 2026년 TypeScript 커뮤니티에서 "새 프로젝트라면 이걸로"라고 자주 거론되는 것들이 한자리에 모여 있다. 그래서 개발자들에게 kaneo는 단순한 할 일 앱이 아니라 "이 스택을 실제 제품에서 어떻게 엮는지 보여 주는 참조 아키텍처(reference architecture)"로 읽힌다. 별을 누르는 손가락의 상당수는 "나도 이렇게 짜고 싶다"는 개발자다.

셋째, AI 시대에 맞는 훅이 있다. kaneo는 kaneo-mcp라는 공식 MCP(Model Context Protocol) 서버를 npm에 배포한다. 덕분에 Claude·Cursor 같은 AI 에이전트가 "3번 프로젝트에 '로그인 버그 수정' 태스크 만들어 줘" 같은 자연어로 실제 보드를 조작할 수 있다. 프로젝트 관리 도구가 "사람이 클릭하는 UI"를 넘어 "에이전트가 호출하는 API"까지 1급으로 제공한다는 점이 시류를 탔다.

3기술 스택 전체 지도

kaneo는 pnpm 워크스페이스 + Turborepo 모노레포다. 하나의 저장소 안에 여러 앱과 공유 패키지가 살고, Turborepo가 이들의 빌드/린트/테스트를 의존성 순서대로 캐시하며 돌린다. 패키지 매니저는 pnpm@10.32.1로 못 박혔고, Node는 >=20.19, 린터/포매터는 ESLint·Prettier가 아니라 Biome 2.5.4(Rust로 짠 초고속 통합 도구) 하나로 통일했다.

앱 (apps/) — 4개

공유 패키지 (packages/) — 5개

• @kaneo/libs — 공유 Hono RPC 클라이언트(client를 export). 프론트가 백을 부를 때 쓰는 타입 연결의 핵심.
• @kaneo/permissions — better-auth 접근제어(RBAC) 역할·리소스 정의. 프론트·백이 같은 권한 정의를 공유.
• @kaneo/mcp — npm에 배포되는 CLI kaneo-mcp(v0.1.6). AI 에이전트용 MCP stdio 서버.
• @kaneo/email — React Email + nodemailer로 만든 트랜잭션 메일(초대·OTP 등).
• @kaneo/typescript-config — 공유 tsconfig 프리셋.

프론트엔드 (apps/web) — 정확한 버전으로

백엔드 (apps/api) — 정확한 버전으로

4아키텍처 심화 — Hono RPC·이벤트 버스·better-auth

전체 그림

축 1 — Hono RPC: tRPC 없이 앞뒤 타입을 잇는다 (이 레포의 하이라이트)

보통 풀스택에서 "프론트가 백 API를 호출"할 때 타입이 끊긴다. 백엔드가 { title: string }을 기대해도, 프론트의 fetch는 그냥 문자열 URL이라 오타·형변환 실수를 런타임에야 안다. 이걸 잇는 유명한 해법이 tRPC지만, kaneo는 Hono가 기본 제공하는 RPC로 같은 효과를 더 가볍게 얻는다.

공유 패키지 @kaneo/libs가 그 클라이언트를 만들어 앱 전체에 나눠 준다:

// packages/libs/src/hono.ts — 프론트 전체가 쓰는 타입세이프 클라이언트
import type { AppType } from "@kaneo/api";   // 백엔드 타입을 그대로 import
import { hc } from "hono/client";

export const client = hc<AppType>(apiUrl, {
  fetch: (input, init) =>
    fetch(input, {
      ...init,
      headers: { ...init?.headers, "Content-Type": "application/json" },
      credentials: "include",   // 쿠키 세션을 항상 함께 전송
    }),
});

축 2 — 3단 프론트 데이터 계층: fetchers → hooks → components

프론트는 API 호출을 컴포넌트에 직접 쓰지 않는다. 세 겹으로 나눈다. ① fetchers/는 연산 하나당 파일 하나로 위 client를 감싼다(예: createTask). ② hooks/는 그 fetcher를 TanStack Query의 useQuery/useMutation으로 감싸, 성공 시 관련 쿼리 키를 무효화(refetch)한다. ③ 컴포넌트는 훅만 부른다. 이 규율 덕에 "데이터를 어떻게 가져오고 캐시를 언제 갱신하는가"가 컴포넌트 밖 한곳에 모인다. 낙관적 업데이트(카드를 놓자마자 UI가 먼저 바뀌고 서버 확인은 뒤따르는)도 이 계층에서 처리된다.

축 3 — API 계층화: 도메인 폴더 → 서브 라우터 → 컨트롤러

백엔드는 task/·project/·column/·workspace/처럼 도메인마다 폴더(약 39개)를 둔다. 각 폴더의 index.ts는 Hono 서브 라우터로, OpenAPI 설명(describeRoute) + Valibot 검증 + 접근제어 미들웨어를 선언하고, 실제 로직은 controllers/의 순수 async 함수에 위임한다. 라우트 정의만 봐도 그 엔드포인트의 문서·검증·권한이 한눈에 들어온다:

// apps/api/src/task/index.ts — 라우트 = 문서 + 검증 + 권한 + 로직
const task = new Hono<{ Variables: { userId: string } }>()
  .get(
    "/tasks/:projectId",
    describeRoute({ operationId: "listTasks", tags: ["Tasks"],
      description: "Get all tasks for a specific project" }),
    validator("param", v.object({ projectId: v.string() })),  // Valibot 검증
    workspaceAccess.fromProject("projectId"),                      // 권한 미들웨어
    async (c) => {
      const { projectId } = c.req.valid("param");
      /* ... 컨트롤러 호출 ... */
    },
  );

축 4 — 이벤트 버스 + 브로드캐스트 어댑터: 실시간을 확장 가능하게

실시간 협업의 설계가 특히 배울 만하다. 컨트롤러는 작업을 마치면 결과를 직접 WebSocket으로 쏘지 않고, 프로세스 내부의 이벤트 버스(Node EventEmitter)에 publishEvent("task.created", ...)로 알리기만 한다. WS 구독자가 그 이벤트를 받아 접속자에게 브로드캐스트한다. 핵심은 이 브로드캐스트가 교체 가능한 어댑터라는 점 — 서버가 1대면 인메모리 어댑터로 충분하고, 여러 대로 늘리면 Redis Pub/Sub 어댑터로 바꿔 서버 간에 이벤트를 퍼뜨린다. 코드 대부분은 그대로 두고 한 조각만 갈아 끼워 단일 서버 → 수평 확장으로 간다.

// apps/api/src/events/index.ts — 행위자(actor)를 추적하는 인프로세스 버스
const EVENTS = new EventEmitter();
export const eventContext = new AsyncLocalStorage<{ initiatorId: string }>();

export async function publishEvent(eventType: string, data: unknown) {
  const store = eventContext.getStore();
  // 누가 일으킨 이벤트인지 실어 보낸다 → 그 사람에겐 WS 에코를 안 보냄
  const enhanced = { ...(data as object), initiatorId: store?.initiatorId };
  EVENTS.emit(eventType, { type: eventType, data: enhanced, timestamp: new Date().toISOString() });
}

축 5 — better-auth: 인증을 직접 짜지 않는다

많은 프로젝트가 로그인·세션·소셜·권한을 직접 구현하다 보안 구멍을 낸다. kaneo는 /api/auth/* 전체를 better-auth에 넘긴다. 이메일+비밀번호(bcrypt), 소셜 로그인(GitHub·Google·Discord), 매직링크·OTP·익명 게스트, 조직(organization) 플러그인으로 "워크스페이스 = 조직", 팀·동적 역할까지, 그리고 API 키·디바이스 인증(MCP/CLI용)이 전부 플러그인 조립으로 켜진다. 권한은 별도 패키지 @kaneo/permissions가 리소스·액션·역할을 코드로 선언해 프론트·백이 같은 정의를 공유한다.

// packages/permissions/src/index.ts — 권한을 코드로 선언(프론트·백 공유)
export const statement = {
  project: ["create", "read", "update", "delete", "share"],
  task:    ["create", "read", "update", "delete", "assign"],
  label:   ["create", "read", "update", "delete"],
  workspace: ["read", "update", "delete", "manage_settings"],
} as const;
export const member = ac.newRole({  // 예: 일반 멤버 역할
  project: ["create", "read"], task: ["create", "read", "update"], workspace: ["read"],
});

5디렉토리 구조 해부

읽는 순서를 추천하면: ①apps/api/src/index.ts(라우터가 어떻게 합쳐지고 AppType이 어디서 나오는지 = 계약서) → ②packages/libs/src/hono.ts(그 타입이 프론트로 건너가는 지점) → ③apps/api/src/database/schema.ts(데이터 모델 전체) → ④apps/api/src/task/(한 도메인이 라우터+컨트롤러로 어떻게 쪼개지는지) → ⑤apps/web/src/hooks/+fetchers/(프론트가 그걸 어떻게 소비하는지) 순이다. 한 도메인(예: task)을 앞뒤로 관통해 읽으면 나머지 38개 도메인은 같은 패턴의 반복이라 빠르게 눈에 들어온다.

6학습 포인트 — 기술별 배울 것

① 타입세이프 풀스택 — Hono RPC로 경계를 봉합

AppType export → hc<AppType> 클라이언트로 코드 생성 없이 앞뒤 타입을 잇는 패턴을 실제 규모에서 관찰한다. tRPC/GraphQL과 무엇이 같고 다른지, 왜 kaneo는 Hono RPC를 골랐는지를 비교하며 배우면 "API 경계 설계"의 안목이 크게 는다.

② 인증을 사지 말고 조립하기 — better-auth

세션·소셜·조직·팀·RBAC·API키·디바이스 플로우를 직접 짜지 않고 플러그인으로 켜는 법. "워크스페이스 = 조직"으로 멀티테넌시를 표현하는 방식은, SaaS를 만들려는 사람이라면 그대로 베껴 쓸 수 있는 청사진이다.

③ 스키마=코드 — Drizzle로 데이터 모델링

32개 테이블을 TypeScript로 선언하고, CUID2 기본키·부분 유니크 인덱스·onDelete: cascade를 어떻게 쓰는지 실물로 익힌다. 스키마 하나에서 타입·마이그레이션·쿼리가 전부 파생되는 경험은 ORM을 보는 눈을 바꾼다.

④ 실시간을 확장 가능하게 — 이벤트 버스 + 어댑터

컨트롤러는 이벤트만 쏘고, 전달은 교체 가능한 어댑터가 맡는다(인메모리 ↔ Redis). 단일 서버에서 시작해 수평 확장으로 가는 길을, 코드를 뒤엎지 않고 여는 방법을 배운다. AsyncLocalStorage로 "행위자 에코 억제"를 처리하는 디테일도 실전 감각을 준다.

⑤ 프론트 데이터 계층의 규율 — TanStack Query

fetchers → hooks → components 3단 분리, 뮤테이션 후 쿼리 키 무효화, 낙관적 업데이트. "데이터 가져오기·캐시 갱신을 컴포넌트 밖 한곳에 모으기"가 왜 유지보수를 살리는지 몸으로 안다.

⑥ 제품 철학 · AI 친화 — 덜어내기와 MCP

"기능을 더하기"가 아니라 "덜어내기"를 규율로 삼는 제품 사고, 그리고 사람이 클릭하는 UI와 에이전트가 부르는 MCP를 동급으로 제공하는 설계. 2026년에 도구를 만든다는 것이 무엇인지를 보여 준다.

7하드웨어 / 시스템 요구사항 (자가호스팅)

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

배경이 이미 있다면 3주(Hono RPC) → 7주(실시간·확장)만 골라 읽어도 kaneo의 두 하이라이트(타입 봉합 + 확장 가능한 실시간)를 잡을 수 있다. 백엔드가 궁금하면 2·3·4·5주, 프론트가 궁금하면 6주가 알짜다.

10핵심 키워드 사전

11참고 링크

• GitHub 저장소 — github.com/usekaneo/kaneo (MIT, TypeScript 모노레포)
• README — 철학("왜 kaneo?")·자가호스팅 3가지 경로(drim/Compose/Helm)
• apps/api/src/index.ts — 도메인 라우터 조립 + AppType export(타입 봉합의 출발점)
• packages/libs/src/hono.ts — hc<AppType> 공유 RPC 클라이언트
• apps/api/src/database/schema.ts — Drizzle 스키마 32개 테이블
• apps/api/src/auth.ts — better-auth 설정(소셜·조직·플러그인)
• packages/permissions · packages/mcp — RBAC 정의 · kaneo-mcp 서버
• 공식 문서 — kaneo.app · 관리형 cloud.kaneo.app · 비교 페이지(/jira-alternative 등)