폴더 규칙
Akan의 폴더는 비즈니스 소유 범위를 기준으로 나뉩니다. 새 기능을 만들 때는 먼저 간단히 물어보면 됩니다. 고객이 방문하는 페이지인가요, 앱이 소유하는 비즈니스 데이터인가요, 공유 UI인가요, 아니면 서버에서만 쓰는 연동 코드인가요?
소유 범위 찾기: 한 제품만 쓰면 해당 앱에 둡니다. 여러 제품이 함께 쓰면 라이브러리로 옮깁니다.
페이지 분리: /orders, /admin/users 같은 화면은 page/ 아래에 둡니다. 재사용 컴포넌트와 로직은 다른 폴더에 둡니다.
비즈니스 모델링: user, order, product, invoice 같은 비즈니스 명사는 보통 lib/ 아래 폴더가 됩니다.
이 파일은 어느 folder로 가는가
누가 쓰는가?
apps/myapp/제품 하나
libs/shared/여러 제품
이 파일은 무엇을 하는가?
page/사용자가 방문하는 URL
lib/model/비즈니스가 저장하는 데이터
lib/_service/비즈니스가 하는 일
ui/재사용하는 마크업
webkit/browser API 또는 React hook
srvkit/node, Bun, 또는 secret
common/순수하고 isomorphic
Commerce app example
워크스페이스 규칙
워크스페이스 루트에서는 코드가 얼마나 넓게 사용되는지를 기준으로 폴더를 선택합니다. 하나의 제품 코드는 apps/에, 여러 제품이 공유하는 코드는 libs/에, 프레임워크 코드는 pkgs/에 둡니다.
Workspace
apps/: 독립적으로 실행되는 비즈니스 제품입니다. 예: 커머스 플랫폼, SaaS 앱, ERP 시스템, 개인용 앱 등
libs/: 여러 앱이 공유하는 제품 코드입니다. 예: 사용자 계정, 결제, 파일 업로드, 소셜, 채팅, 보안, 관리자 기능 등.
pkgs/: 특수한 목적을 가진 코드로써, npm 패키지처럼 사용하거나 배포되는 폴더입니다. 예: 결제 연동 라이브러리, 로봇 특화 제어 코드 등
.akan/과 dist/ 같은 생성 폴더는 빌드 결과물이며, 일반적으로 직접 수정하지 않습니다.
pkgs/는 코드가 별도 설치 패키지처럼 독립적으로 느껴질 때만 사용합니다. 한 앱의 일반 비즈니스 로직은 apps/에, 여러 제품이 공유하는 제품 로직은 보통 먼저 libs/에 둡니다.
앱/라이브러리 폴더 규칙
앱은 제품이 사용자에게 보이는 공간입니다. 라이브러리는 재사용 가능한 비즈니스 기능이 사는 공간입니다. 둘 다 도메인 모듈, UI, 자산, 서버 헬퍼를 가질 수 있기 때문에 구조가 비슷합니다.
apps/myapp/
libs/shared/
각 폴더에는 느낌이 아니라 들어올 수 있는 조건이 있고, 첫 열은 그 코드가 클라이언트 경계의 어느 쪽에서 도는지를 말합니다. client 폴더는 브라우저까지 전송되므로 비밀값이 닿아서는 안 되고, shared 폴더는 양쪽에서 읽으므로 순수하고 환경에 안전해야 합니다. 어떤 조건에도 맞지 않는 파일은 애초에 앱·라이브러리 루트에 두지 않습니다.
폴더설명
page/
client — 사용자가 방문하는 화면입니다. 기능에 자기 URL이 있으면 여기에 페이지를 둡니다. 예: page/orders.tsx는 /orders를 엽니다.
lib/
shared — 비즈니스 데이터와 그에 딸린 규칙입니다. 기능이 저장하는 대상을 가지면 모듈 폴더로 만듭니다. 예: lib/order/에 주문 데이터와 동작을 둡니다.
ui/
client — 여러 페이지에서 재사용하는 화면 조각이며 특정 모델에 묶이지 않습니다. 예: 여러 곳에서 쓰는 카드나 차트.
webkit/
client — 브라우저나 기기 기능이 필요하거나 React hook인 코드입니다. 예: 클립보드 헬퍼, 카메라 hook.
common/
shared — 서버와 클라이언트가 함께 쓰는 작은 순수 헬퍼입니다. 예: 날짜 포맷, 문자열 유틸.
srvkit/
server — 외부 서비스에 연결하는 코드입니다. 예: 결제 API 클라이언트, 메일 발송기.
env/
shared — 환경마다 달라지는 설정입니다. 예: local과 production의 API 호스트.
plugin/
shared — 앱이 빌드되거나 실행되는 방식을 바꾸는 코드입니다. 예: 빌드 때 이미지 크기를 생성하는 플러그인.
native/
client — 직접 가진 네이티브 플러그인이며, 플러그인 id마다 폴더 하나입니다. 예: native/label-printer/에 페이지 API, Kotlin, Swift.
public/
client — 가공 없이 그대로 제공되는 파일입니다. 예: 이미지, 폰트, robots.txt.
private/
server — 서버가 실행 중에 읽고 브라우저에는 내보내지 않는 애셋 폴더입니다. 예: ONNX 모델 파일, 고정 JSON 데이터셋.
script/
server — 실행 중인 앱에 손으로 돌리는 개발용 스크립트입니다. 예: 테스트 데이터 넣기.
헷갈릴 때는 파일이 하는 일을 물어보세요. 화면은 page/, 재사용 화면 조각은 ui/, 저장되는 비즈니스 데이터는 lib/<model>/, 비공개 서버 연동은 srvkit/ 또는 lib/_<service>/에 둡니다.
모듈 폴더 규칙
lib/ 안에서는 폴더 이름이 만들고 있는 비즈니스 개념의 종류를 설명합니다. 비즈니스가 소유하는 데이터는 일반 폴더, 기능이나 외부 연동은 밑줄 폴더, 재사용 값 형태는 __scalar에 둡니다.
lib/
lib/<model>/: 비즈니스가 소유하고 저장하는 명사에 사용합니다. business intent, domain rule, workflow, agent note를 위해 model.abstract.md를 함께 둡니다.
lib/_<service>/: 행동, 워크플로우, 연동 기능에 사용합니다. 폴더에는 밑줄을 유지하지만 abstract 파일명은 lib/_payment/payment.abstract.md처럼 밑줄을 제외합니다.
lib/__scalar/<type>/: 여러 모델이 함께 쓰는 값 형태에 사용합니다. validation 의미나 재사용 규칙 설명이 필요하면 scalar.abstract.md를 함께 둡니다.
간단한 기준은 이렇습니다. '저장하는 대상'이라면 lib/<model>/을, '수행하는 기능'이라면 lib/_<service>/를 사용하세요.
외부 연동에서는 벤더 API를 직접 다루는 낮은 수준의 클라이언트는 srvkit/에 두고, 앱이 이해하는 비즈니스 워크플로우는 lib/_<service>/에 둡니다. 예를 들어 paymentGateway.ts는 결제사 API를 호출하고, lib/_payment는 주문 결제를 생성합니다.
성장에 따른 이동
비즈니스가 성장하면 코드의 위치도 바뀔 수 있습니다. 처음에는 제품 가까이에 두고, 실제로 공유나 패키징이 필요해질 때 바깥으로 옮기면 됩니다.
Code movement
apps/: 기능이 하나의 제품에만 속한다면 여기서 시작합니다. 초기 비즈니스 코드를 찾기 쉽습니다.
libs/: 두 개 이상의 앱이 같은 비즈니스 모델, UI, 서비스 흐름을 필요로 할 때 옮깁니다.
pkgs/: 자체 패키지 경계를 가진 독립 코드가 되어야 할 때만 옮깁니다.