사람함께에이전트▾

사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.

함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.

에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.

워크스페이스▾

앱 & 라이브러리▾

애셋 (public/ private/)컴포넌트 (ui/)서버 유틸리티 (srvkit/)웹 유틸리티 (webkit/)공통 유틸리티 (common/)akan.config.ts

도메인▾

개요 model.abstract.md model.constant.ts model.dictionary.ts model.document.ts model.service.ts model.signal.ts model.store.ts Model.Template.tsx Model.Unit.tsx Model.Util.tsx Model.View.tsx Model.Zone.tsx

스칼라▾

개요 scalar.abstract.md scalar.constant.ts scalar.dictionary.ts scalar.document.ts Scalar.Template.tsx Scalar.Unit.tsx

서비스▾

개요 service.abstract.md service.dictionary.ts service.service.ts service.signal.ts service.store.ts Service.Util.tsx Service.Zone.tsx

모듈 개요

Akan 모듈은 비즈니스 기능 하나를 담는 폴더입니다. 모델의 모양, 화면 문구, 저장 방식, 비즈니스 흐름, API, 클라이언트 상태, UI가 한 폴더에 나란히 놓입니다.

이 페이지는 다음에 열 파일을 고르기 위한 지도입니다. 문법과 예시는 파일별 문서에 있습니다.

예시 모듈

libs/shared의 banner 모듈은 이렇게 생겼습니다:

libs/shared/lib/banner/

소문자 파일은 로직입니다. <model>.<역할>.ts 이름으로 데이터, 저장, API, 클라이언트 상태를 맡습니다.
PascalCase 파일은 UI입니다. 컴포넌트는 모델 네임스페이스로 부릅니다. Banner.Unit.tsx의 Card는 <Banner.Unit.Card />입니다.
index.ts는 자동 생성됩니다. 손으로 고치지 않습니다. *.signal.spec.ts에는 테스트 fixture를, *.signal.test.ts에는 검증을 둡니다.
이 페이지는 데이터베이스 모듈을 다룹니다. 위치는 lib/<model>입니다. 서비스 모듈(lib/_<service>)과 스칼라 모듈(lib/__scalar/<scalar>)은 개요 문서가 따로 있습니다.

이 페이지에서 쓰는 말

용어설명

light model

Light<Model> 클래스입니다. 목록이나 카드에 필요한 필드 몇 개만 담고, 서버와 클라이언트가 모두 가집니다.

full model

<Model> 클래스입니다. 레코드 하나의 모든 필드를 담고, 상세 화면에서 씁니다.

slice

클라이언트 store의 목록을 채우는 서버 쿼리입니다.

endpoint

호출하는 쪽이 부를 수 있는 query, mutation, message, pubsub 하나입니다.

guard

호출한 사람이 endpoint를 실행해도 되는지 판정하는 클래스입니다.

Load.UnitsLoad.View

route가 넘긴 데이터로 store를 채우고, 로딩 상태와 빈 상태를 대신 그려 주는 래퍼입니다.

모듈 파일 지도

모듈 파일은 두 가지로 나뉩니다. 소문자 로직 파일 일곱 개와 PascalCase UI 파일 다섯 개입니다. 카드를 누르면 그 파일의 문서로 이동합니다.

로직 파일

model.abstract.md→

모듈이 맡는 일, 코드로는 드러나지 않는 규칙 2~5개, 필요하면 상태 흐름을 적습니다. 가장 먼저 읽습니다.

model.constant.ts→

데이터 모양입니다. 필드, enum, 모델 다섯 단계, 헬퍼, hidden/secret 필드, resolve 필드를 정의합니다.

model.dictionary.ts→

사용자가 읽는 말입니다. 필드, insight, query, sort, enum, slice, endpoint, 에러, UI 문구에 이름을 붙입니다.

model.document.ts→

저장된 document의 동작입니다. filter, document method, 모델 헬퍼, index, schema hook을 정의합니다.

model.service.ts→

비즈니스 흐름입니다. document method, 주입받은 service, 데이터베이스 작업을 엮어 구현합니다.

model.signal.ts→

서버 작업이 시작되는 곳입니다. slice, endpoint, 실시간 message와 pubsub, 내부 작업, guard, resolve 필드를 둡니다.

model.store.ts→

클라이언트 상태입니다. 폼·목록 상태, 생성된 fetch 호출, 토스트, UI가 부르는 action을 맡습니다.

UI 파일

Unit과 View는 서버 컴포넌트입니다. Template, Zone, Util은 클라이언트 컴포넌트라서 첫 줄에 "use client"를 붙입니다.

Model.Template.tsx→

폼입니다. 각 필드를 생성된 setter로 store의 폼 상태에 연결합니다.

Model.Unit.tsx→

light model을 그리는 작은 조각입니다. 카드, 행, 아바타, 열, 짧은 요약 같은 것입니다.

Model.View.tsx→

full model 하나의 상세 화면입니다. 상세 페이지, 보기 모달, 모든 필드가 필요한 섹션에 씁니다.

Model.Util.tsx→

작은 클라이언트 컨트롤입니다. 액션 버튼, 툴박스, 다이얼로그, 쿼리 패널, 내비게이션 도우미 등이 있습니다.

Model.Zone.tsx→

페이지 섹션입니다. route가 넘긴 데이터를 Load.Units나 Load.View에 넣고 Unit, View, Util을 조립합니다.

서버에서 클라이언트까지

모듈은 보통 데이터 모양에서 시작해 저장, API, 클라이언트 상태, UI 순서로 자랍니다. 모든 기능에 모든 파일이 필요하지는 않지만, 이 순서를 따르면 파일마다 맡은 일이 분명해집니다.

abstract — 비즈니스 의도와 오래 유지될 도메인 규칙부터 적습니다.
constant — 필드, enum, 모델 단계로 비즈니스 데이터의 모양을 정합니다.
dictionary — 그 필드, 동작, 에러, UI 문구에 사용자가 볼 이름을 붙입니다.
document — 저장된 document를 조회하고, 바꾸고, 인덱싱하고, 불러오는 방식을 정합니다.
service — document 헬퍼와 다른 service를 엮어 비즈니스 흐름을 구현합니다.
signal — 서버 동작을 타입이 있는 slice, endpoint, 실시간 채널, 작업으로 공개합니다.
store — 생성된 fetch API를 클라이언트 상태, 폼 상태, UI action에 연결합니다.
UI — 폼, 목록, 상세 화면, 동작, 페이지 섹션을 그립니다.

그림으로 보면 흐름은 UI에서 끝나고, UI는 다섯 역할로 갈라집니다:

모듈 하나, 데이터에서 UI까지

constant

dictionary

document

service

signal

store

Template폼

Unit행 하나 또는 카드

View레코드 하나 전체

Util컨트롤 하나

Zone섹션

역할 경계

모듈이 헷갈리기 시작했다면 대개 로직이 엉뚱한 파일에 들어간 것입니다. 코드를 더하기 전에 아래 표에서 자리를 확인하세요.

무엇을	어디에	담는 것
비즈니스 규칙	service · document · constant	service 흐름, document method, constant 헬퍼로 둡니다. render 코드 안에 숨기지 않습니다.
API와 접근 권한	signal	slice, endpoint, guard, internal arg, 실시간 채널, 작업을 둡니다.
클라이언트 조율	store	fetch 호출, 폼·목록 상태, 토스트, UI action을 둡니다.
표시	Unit · View	반복되는 light model은 Unit, full model 하나의 상세는 View로 그립니다.
페이지 섹션	Zone	Load 래퍼, Unit/View, Util 컨트롤, 섹션 배치를 조립합니다.
작은 컨트롤	Util	툴박스, 액션 버튼, 다이얼로그를 여는 버튼, 쿼리 패널, 내비게이션 도우미를 둡니다.

UI와 store 파일은 서버 로직을 import하지 않습니다. *.store.ts나 .tsx 파일이 *.document.ts, *.dictionary.ts, *.service.ts, *.signal.ts를 import하거나 그 반대로 import하면 lint 오류로 빌드가 멈춥니다. UI 코드는 @apps/<app>/client나 @libs/<lib>/client에서 cnst, fetch, st를 가져오고, import type은 어느 방향이든 괜찮습니다.

실전 규칙

모듈을 따라 읽기 쉽게 유지하는 습관 네 가지입니다:

파일은 생성된 타입으로 잇습니다. 모양을 손으로 복사하지 말고 cnst, fetch, st가 파일 사이를 잇게 둡니다.
UI보다 서버가 먼저입니다. 기능이 저장된 데이터를 바꾼다면 서버 동작부터 설계합니다.
UI 파일은 조립하고 보여 주기만 합니다. 비즈니스 결정을 그 안에 숨기지 않고, 표시나 판정 규칙은 Light<Model>의 메서드로 둡니다.
Zone을 키우기 전에 나눕니다. 섹션이 커지면 표시는 Unit/View로, 컨트롤은 Util로 먼저 옮깁니다.

이전akan.config.ts 다음model.abstract.md

모듈 개요

모듈 파일 지도

서버에서 클라이언트까지

역할 경계

추천 읽기 순서

실전 규칙