폴더 규칙

Akan의 폴더는 비즈니스 소유 범위를 기준으로 나뉩니다. 새 기능을 만들 때는 먼저 간단히 물어보면 됩니다. 고객이 방문하는 페이지인가요, 앱이 소유하는 비즈니스 데이터인가요, 공유 UI인가요, 아니면 서버에서만 쓰는 연동 코드인가요?

소유 범위 찾기: 한 제품만 쓰면 해당 앱에 둡니다. 여러 제품이 함께 쓰면 라이브러리로 옮깁니다.

페이지 분리: /orders, /admin/users 같은 화면은 page/ 아래에 둡니다. 재사용 컴포넌트와 로직은 다른 폴더에 둡니다.

비즈니스 모델링: user, order, product, invoice 같은 비즈니스 명사는 보통 lib/ 아래 폴더가 됩니다.

Commerce app example

워크스페이스 규칙

워크스페이스 루트에서는 코드가 얼마나 넓게 사용되는지를 기준으로 폴더를 선택합니다. 하나의 제품 코드는 apps/에, 여러 제품이 공유하는 코드는 libs/에, 프레임워크 코드는 pkgs/에 둡니다.

Workspace

apps/: 독립적으로 실행되는 비즈니스 제품입니다. 예: 커머스 플랫폼, SaaS 앱, ERP 시스템, 개인용 앱 등

libs/: 여러 앱이 공유하는 제품 코드입니다. 예: 사용자 계정, 결제, 파일 업로드, 소셜, 채팅, 보안, 관리자 기능 등.

pkgs/: 특수한 목적을 가진 코드로써, npm 패키지처럼 사용하거나 배포되는 폴더입니다. 예: 결제 연동 라이브러리, 로봇 특화 제어 코드, 블록체인 연동 코드 등

.akan/과 dist/ 같은 생성 폴더는 빌드 결과물입니다. Akan이 빠르게 실행되도록 돕지만, 일반적으로 직접 수정하지 않습니다.

pkgs/는 코드가 별도 설치 패키지처럼 독립적으로 느껴질 때만 사용합니다. 한 앱의 일반 비즈니스 로직은 apps/에, 여러 제품이 공유하는 제품 로직은 보통 먼저 libs/에 둡니다.

앱/라이브러리 폴더 규칙

앱은 제품이 사용자에게 보이는 공간입니다. 라이브러리는 재사용 가능한 비즈니스 기능이 사는 공간입니다. 둘 다 도메인 모듈, UI, 자산, 서버 헬퍼를 가질 수 있기 때문에 구조가 비슷합니다.

apps/myapp/

libs/shared/

클라이언트

브라우저나 클라이언트 앱에서 실행됩니다. 비밀값을 넣으면 안 됩니다.

서버

서버에서 실행됩니다. 비공개 API 호출, 스크립트, 보호된 로직에 적합합니다.

공용

서버와 클라이언트 양쪽에서 사용할 수 있습니다. 순수하고 환경에 안전한 코드로 유지하세요.

page/

client

사용자가 URL로 방문하는 화면을 둡니다. 예: 홈, 로그인, 상품 상세, 관리자 대시보드.

lib/

shared

비즈니스 개념을 둡니다. 예: user, product, order, invoice, payment, notification.

ui/

client

재사용 가능한 화면 컴포넌트를 둡니다. 예: Header, ProductCard, DatePicker, EmptyState.

common/

shared

서버와 클라이언트가 모두 접근할 수 있는 공유 코드를 둡니다. 예: 포맷터, 검증 함수, 상수, 순수 유틸리티.

webkit/

client

브라우저/클라이언트 헬퍼를 둡니다. 예: 알림 hook, 디바이스 API, 로컬 스토리지, 웹 전용 동작.

env/

shared

Akan이 생성하거나 사용하는 환경별 어댑터와 환경 파일을 둡니다.

public/

client

정적 파일을 둡니다. 예: 로고, 아이콘, 폰트, 다운로드용 PDF, 샘플 이미지.

srvkit/

server

서버에서만 쓰는 헬퍼를 둡니다. 예: 결제 API 클라이언트, 클라우드 SDK 래퍼, 비공개 스크립트.

private/

server

앱이나 라이브러리의 공개 API가 되면 안 되는 내부 구현 코드를 둡니다.

script/

server

개발 중 Akan 서버를 켠 상태에서 실행하는 스크립트를 둡니다.

헷갈릴 때는 파일이 하는 일을 물어보세요. 화면은 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/: 자체 패키지 경계를 가진 독립 코드가 되어야 할 때만 옮깁니다.