파일 규칙

폴더 이름은 파일이 어떤 비즈니스 영역에 속하는지 알려줍니다. 파일 이름은 그 비즈니스 영역 안에서 어떤 역할을 하는지 알려줍니다. 예를 들어 product.document.ts는 저장되는 상품 데이터를 설명하고, Product.View.tsx는 상품 데이터를 화면에 어떻게 보여줄지 설명합니다.

모듈을 작은 비즈니스 부서라고 생각하면 쉽습니다. product 모듈은 상품에 어떤 필드가 있는지, 어떻게 저장하는지, 사용자가 어떻게 요청하는지, 관리자 화면에서 어떻게 보여줄지까지 다룰 수 있습니다. 각 파일은 그중 하나의 역할을 맡습니다.

lib/product/

비즈니스 의미: 파일 접미사는 해당 모델에서 어떤 일을 담당하는지 설명합니다.

스캔 가능한 규칙: Akan은 이 접미사를 스캔해서 모델, 서비스, 시그널, UI 조각을 연결합니다.

작게 시작: 모든 파일이 항상 필요한 것은 아닙니다. 비즈니스 기능에 필요할 때만 추가하면 됩니다.

처음부터 모든 파일을 만들 필요는 없습니다. 예를 들어 단순히 보여주기만 하는 상품 카탈로그라면 처음에는 product.document.ts와 Product.View.tsx만으로 시작할 수 있습니다.

모듈 파일

이 파일들은 비즈니스 모델의 데이터, 서버 로직, API 표면, 상태를 설명합니다. 상품, 주문, 사용자, 청구서, 예약 같은 기능을 만들 때 가장 자주 다루게 됩니다.

예를 들어 주문 기능을 만든다면 order.constant.ts에는 주문 상태값을, order.document.ts에는 저장되는 주문 필드를, order.service.ts에는 결제 완료 처리 로직을, order.signal.ts에는 페이지에서 호출할 수 있는 동작을 둘 수 있습니다.

model.constant.ts

shared

상수, 상태값, 기본 옵션, 모델에서 공유하는 타입을 둡니다. 예: pending, paid, shipped 같은 주문 상태.

model.dictionary.ts

shared

모델에서 쓰는 라벨, 필드 이름, 문구 키를 둡니다. 예: 상품명, 가격, 재고 라벨.

model.document.ts

server

저장되는 데이터 형태, 필터, 문서 모델 정의를 둡니다. 예: 청구서가 어떤 필드를 저장하고 어떻게 조회되는지.

model.service.ts

server

서버 측 비즈니스 로직을 둡니다. 예: 주문 생성, 쿠폰 적용, 배송비 계산, 결제 완료 처리.

model.signal.ts

shared

페이지에서 호출할 수 있는 공개 동작, slice, endpoint, 내부 작업을 둡니다. 예: 주문 목록 불러오기, OCR 요청하기.

model.store.ts

client

여러 화면에서 쓰는 클라이언트 상태 또는 모델 상태를 둡니다. 예: 선택된 필터, 장바구니 상태, 임시 폼 상태.

UI 파일

UI 파일은 모델이 화면에 어떻게 보이는지 설명합니다. React 컴포넌트나 UI 묶음을 export하므로 PascalCase 이름을 사용합니다.

하나의 비즈니스 모델은 여러 화면 크기로 등장합니다. 작은 배지, 목록 행, 상세 카드, 관리자 패널, 대시보드 섹션처럼 다양한 형태가 생깁니다. UI 파일은 이런 화면 조각을 해당 모델 가까이에 모아두도록 도와줍니다.

lib/bizCard/

Model.View.tsx: ProductCard, OrderSummary, UserProfile, InvoicePreview처럼 데이터를 보여주는 컴포넌트에 사용합니다.

Model.Unit.tsx: 상태 배지, 가격 행, 아바타 블록처럼 모델 UI 안에서 재사용되는 작은 단위 컴포넌트에 사용합니다.

Model.Template.tsx: 표준 관리자 상세 레이아웃처럼 반복되는 화면 템플릿이나 레이아웃 패턴에 사용합니다.

Model.Util.tsx: 삭제 버튼, 수정 모달 트리거, 업로드 컨트롤처럼 UI 레벨 액션이나 보조 컴포넌트에 사용합니다.

Model.Zone.tsx: 관리자 화면, 목록/상세 영역, 탭 콘텐츠, 대시보드 섹션처럼 큰 화면 구역에 사용합니다.

이름 규칙

Akan 파일 이름은 두 가지 패턴을 사용합니다. 비즈니스 핵심 파일은 모델 이름을 lower camel case로 쓰고, UI 파일은 PascalCase로 씁니다.

이 규칙을 지키면 모듈을 눈으로 훑기 쉬워집니다. lib/product/를 열었을 때 product.* 파일은 비즈니스 로직이고 Product.* 파일은 UI라는 것을 바로 알 수 있습니다. 새 조회, 화면 컴포넌트, 서버 동작을 어디에 추가할지 빠르게 판단할 수 있습니다.

비즈니스 파일

UI 파일

모듈 폴더 안에서는 이 규칙을 벗어난 임의의 파일 선언을 금지합니다. 예를 들어 product.helper.ts나 ProductComponents.tsx는 product.service.ts, Product.Util.tsx, Product.Unit.tsx처럼 가장 가까운 허용 역할로 옮겨야 합니다.

접미사는 단순한 스타일이 아닙니다. Akan은 이 접미사를 스캔해서 각 모듈에 어떤 파일이 있는지 이해합니다.

Facet 파일과 Barrel

ui/와 webkit/ 아래 파일은 보통 @apps/myapp/ui, @libs/shared/webkit 같은 barrel 파일을 통해 export됩니다. import를 예측하기 쉽고 최적화하기 좋게 유지하려면, 한 파일에는 대표 export 하나를 두고 파일명과 export 이름을 맞추는 것을 권장합니다.

이 규칙은 비즈니스가 커질수록 특히 유용합니다. 스토어, 관리자 앱, 파트너 앱이 모두 ProductCard를 가져다 쓰더라도 실제 구현 위치를 자세히 알 필요가 없습니다.

✅ 권장

❌ 피하기

ui/: 재사용 가능한 화면 컴포넌트에 사용합니다. 예: ProductCard.tsx는 ProductCard를 export하는 것이 좋습니다.

webkit/: 브라우저/클라이언트 hook과 helper에 사용합니다. 예: usePaymentStatus.tsx는 usePaymentStatus를 export하는 것이 좋습니다.

Barrel Imports

barrel 파일은 여러 파일을 하나의 진입점에서 다시 export하는 파일입니다. Akan은 설정된 barrel import를 분석해서 정확한 원본 파일 import로 바꿀 수 있으므로, @apps/myapp/ui에서 편하게 가져오면서도 항상 전체 barrel을 번들에 끌어오지 않도록 도와줍니다.

일상적인 제품 개발에서는 깊은 파일 경로 대신 비즈니스 이름으로 import할 수 있다는 뜻입니다. 개발자는 깔끔한 import를 작성하고, Akan은 실제로 쓰는 파일만 빌드에 포함되도록 도와줍니다.

barrel import

그래서 한 파일에 대표 export 하나를 두는 방식을 권장합니다. ProductCard가 ui/ProductCard.tsx에서 왔다는 것을 barrel analyzer가 명확하게 매핑할 수 있습니다.

모듈별 차이

모든 폴더 타입이 모든 파일 타입을 쓰는 것은 아닙니다. database module은 전체 파일 구성을 가질 수 있고, service module은 동작 중심이며, scalar module은 재사용 값 정의 중심입니다.

폴더의 비즈니스 역할에 따라 파일 구성을 선택합니다. product는 저장하는 대상이므로 document와 store 파일을 가질 수 있습니다. _payment는 수행하는 기능이므로 보통 service와 signal 중심입니다. money는 재사용 값 형태이므로 작고 정의 중심으로 유지합니다.

lib/<model>/: constant, dictionary, document, service, signal, store, Template, Unit, Util, View, Zone을 사용할 수 있습니다.

lib/_<service>/: dictionary, service, signal, store, Util, Zone을 사용할 수 있습니다.

lib/__scalar/<type>/: constant, dictionary, document을 사용할 수 있습니다.

자동생성과 선택 기준

Akan은 모듈 파일을 스캔하고 그 주변에 필요한 helper index를 생성합니다. 그래서 애플리케이션 코드는 각 파일을 직접 연결하지 않고 안정적인 모듈 export를 통해 기능을 가져올 수 있습니다.

제품 팀 입장에서는 반복적인 연결 작업이 줄어듭니다. 모듈이 document에서 시작해 view, unit, zone으로 커져도 파일 이름이 컨벤션을 따르면 Akan이 모듈 진입점을 정리해줄 수 있습니다.

Generated UI index idea

그래서 이름 규칙이 중요합니다. Product.View.tsx를 임의로 바꾸면 Akan은 그 파일을 Product 모듈의 View 파일로 인식할 수 없습니다.

자주 하는 선택

어떤 파일을 만들어야 할지 모르겠다면, 해결하려는 비즈니스 질문에서 시작하면 됩니다.

예를 들어 '고객이 주문을 볼 수 있나요?'는 View로 이어집니다. '고객이 주문을 취소할 수 있나요?'는 signal과 service로 이어집니다. '주문이 어떤 필드를 저장하나요?'는 document로 이어집니다.

이 데이터를 저장하나요?: model.document.ts

서버에서 처리하나요?: model.service.ts

페이지에서 호출하나요?: model.signal.ts

데이터를 보여주나요?: Model.View.tsx

작은 UI 액션인가요?: Model.Unit.tsx or Model.Util.tsx

큰 화면 영역인가요?: Model.Zone.tsx