UI 아키텍처

Akan UI는 앱에서 사용자가 직접 마주하는 인터페이스 계층입니다. 고객이 상품 페이지를 열고, 관리자가 재고를 수정하고, 파트너가 다른 클라이언트에서 주문을 확인할 때 UI는 무엇을 즉시 보여줄지, 무엇을 인터랙티브하게 만들지, 사용자 행동을 백엔드로 어떻게 전달할지 결정합니다.

빠른 첫 화면: 서버 렌더링 페이지는 브라우저가 인터랙티브해지기 전에도 카탈로그, 글, 대시보드 내용을 먼저 보여줄 수 있습니다.

인터랙티브 작업: 클라이언트 컴포넌트는 폼, 필터, 재고 변경, 실시간 대시보드, 브라우저/디바이스 API를 처리합니다.

생성된 헬퍼: 생성된 fetch, store, model namespace가 직접 작성해야 하는 API/상태 연결 코드를 줄여줍니다.

여러 클라이언트 표면: 고객 웹, 관리자 콘솔, 파트너 사이트, 모바일 앱은 백엔드 로직을 공유하면서 서로 다른 화면을 보여줄 수 있습니다.

서버사이드 렌더링이란?

서버사이드 렌더링은 브라우저가 전체 앱을 모두 불러오기 전에 서버가 먼저 보이는 HTML을 준비해 보내는 방식입니다. 모든 버튼, 입력, 실시간 기능이 동작 가능해지기 전에도 사용자는 유용한 콘텐츠를 더 빨리 볼 수 있습니다.

서버가 먼저 준비

서버는 route, params, language, 초기 데이터를 읽고 사용자가 처음 볼 페이지를 준비합니다.

product list, article body, reservation summary

브라우저가 먼저 표시

브라우저는 의미 있는 콘텐츠를 빠르게 그릴 수 있어, 사용자는 빈 앱 껍데기만 보고 기다리지 않아도 됩니다.

title, price, first rows, policy text

클라이언트가 활성화

첫 화면이 보인 뒤 클라이언트 컴포넌트가 입력, 클릭, 필터링, 실시간 업데이트를 위한 이벤트 핸들러를 붙입니다.

forms, filters, modals, st, fetch

SSR 동작 흐름

중요한 점은 화면을 보는 순간과 조작할 수 있는 순간이 꼭 같은 시점일 필요는 없다는 것입니다.

서버

route, params, language, 초기 데이터로 첫 HTML을 준비합니다.

article title, product list

→

브라우저 표시

사용자가 페이지를 이해할 수 있도록 유용한 콘텐츠를 빠르게 그립니다.

Time to View

→

클라이언트 영역

폼, 필터, 모달, 실시간 업데이트, st, fetch 액션을 활성화합니다.

Time to Interaction

비즈니스 예시

쇼핑 페이지에서는 고객이 상품명, 가격, 첫 목록을 빠르게 봐야 합니다. 장바구니 버튼, 재고 필터, 추천 캐러셀은 첫 화면이 이미 보인 뒤 인터랙티브해져도 됩니다.

SSR은 클라이언트 UI의 반대 개념이 아닙니다. 사용자 경험의 첫 단계입니다. 유용한 콘텐츠를 먼저 보여주고, 상호작용이 필요한 부분은 클라이언트 컴포넌트가 맡습니다.

렌더링 경계

서버사이드와 클라이언트사이드를 나누기 전에 사용자 경험의 두 순간을 먼저 생각하세요. 사용자가 유용한 내용을 볼 수 있는 순간과, 그 화면을 실제로 조작할 수 있는 순간입니다.

Time to View

사용자가 의미 있는 내용을 얼마나 빨리 볼 수 있는지입니다. 모든 버튼이 동작 가능해지기 전이라도 고객은 상품명, 가격, 글 본문, 예약 정보를 먼저 볼 수 있어야 합니다.

Server-side rendering helps here

Time to Interaction

사용자가 입력, 클릭, 필터링, 모달 열기, 실시간 업데이트 수신을 얼마나 빨리 할 수 있는지입니다. 이런 작업에는 브라우저 쪽 상태와 이벤트 핸들러가 필요합니다.

Client-side components help here

왜 두 방식을 함께 쓰는가

서버사이드 첫 콘텐츠

사용자가 즉시 이해해야 하는 콘텐츠에 좋습니다. 카탈로그 목록, 글 페이지, 가격, 프로필 요약, 정책 문구가 여기에 해당합니다.

클라이언트사이드 작업 영역

사용자 행동에 반응해야 하는 부분에 좋습니다. 재고 폼, 필터, 채팅 입력, 대시보드, 지도, 카메라, 로컬 디바이스 API가 여기에 해당합니다.

더 쉬운 결정 순서

사용자가 먼저 봐야 하는 것부터 시작하고, 실제로 상호작용이 필요한 영역에만 브라우저 작업을 추가합니다.

안정적인 콘텐츠 표시

상품명, 글 본문, 가격, 요약, 첫 목록은 서버에서 렌더링합니다.

page.tsx, layout, first data

작업 영역 감싸기

폼, 필터, 모달, 실시간 상태, 디바이스/브라우저 API 주변에만 "use client"를 사용합니다.

Edit, filter, modal, live status

액션 연결

클라이언트 상태는 st로 다루고, 서버의 비즈니스 응답이 필요하면 fetch를 사용합니다.

st.use, st.do, fetch

먼저 읽히는 화면으로 시작: 사용자가 상품명, 가격, 글, 요약 정보를 즉시 봐야 한다면 그 부분은 서버 렌더링으로 둡니다.

작업이 필요한 곳만 클라이언트: 사용자가 입력, 클릭, 모달 열기, 목록 필터링을 하거나 로드 후 화면이 계속 바뀌어야 할 때 클라이언트 컴포넌트를 사용합니다.

경계에 use client 선언: 기본적으로 전체 페이지를 클라이언트 페이지로 만들지 않습니다. 인터랙션이 필요한 가장 작은 컴포넌트에 "use client"를 둡니다.

화면 영역별로 섞어서 사용: 상품 페이지 대부분은 서버 렌더링으로 두고, 필터, 장바구니 버튼, 재고 폼 같은 영역만 브라우저에서 실행할 수 있습니다.

페이지 구성 패턴

일반적인 비즈니스 화면은 서버에서 렌더링되는 껍데기와 클라이언트에서 동작하는 영역을 함께 사용합니다. 상품 목록 페이지는 제목과 첫 데이터를 서버에서 렌더링하고, 목록 영역은 페이지네이션, 필터, 실시간 업데이트, 사용자 액션을 위해 클라이언트 zone에 넘길 수 있습니다.

예시 모델

Article

하나의 모델은 page 진입점부터 backend 호출까지 예측 가능한 UI 계층을 만듭니다.

→

page

index, new, [id], [id]/edit

비즈니스 화면과 URL 단위 진입점입니다.

component

Unit, Edit, View, Util, Zone

표시, 폼, 액션, 클라이언트 zone을 위한 재사용 화면 조각입니다.

store

model, modelList, modelForm, modelModal

목록, 폼, 선택된 데이터, 모달을 위한 클라이언트 상태입니다.

fetch

initModel, createModel, updateModel...

UI 액션을 백엔드 signal에 연결하는 생성 호출입니다.

st 클라이언트 상태관리

page와 component 구조가 정리되면 브라우저가 가져야 할 상태를 정합니다. st는 폼 값, 선택된 행, 로딩 상태, 필터, 파생 라벨처럼 작업 중인 상태에 사용합니다.

UI action state flow

stateBuilder: 사용자가 작업하는 동안 바뀌는 writable state를 선언합니다. stockDraft, saving 같은 값입니다.

derivedState: writable state에서 계산되는 값을 선언합니다. stockDraft와 saving으로 만든 canSubmitStock 같은 값입니다.

st.get / st.set: store action 안에서 비즈니스 작업 전후의 상태를 읽고 변경합니다.

st.use.field / st.do.setField: 컴포넌트는 st.use.*로 field를 구독하고, 모델 폼은 setNameOnProduct 같은 생성 setter를 사용합니다.

focus, hover, 일회성 입력 초안처럼 작은 UI 전용 값은 컴포넌트 local state로 충분합니다. 여러 컴포넌트가 공유하거나, action에서 필요하거나, 화면 흐름 동안 유지되어야 하는 값은 st에 둡니다.

Stock store with state and derivedState

fetch 서버 호출

컴포넌트가 필요한 상태를 모았고 서버 측 비즈니스 판단이 필요할 때 fetch를 사용합니다. 서버는 signal endpoint를 선언하고, Akan은 클라이언트 함수를 생성하며, store action은 이를 호출합니다.

fetch 직접 호출

컴포넌트가 많은 상태를 조율하지 않는 단순 초기 데이터나 일회성 조회에 적합합니다.

Fetch directly flow

store action으로 감싸기

폼과 비즈니스 액션에 적합합니다. action이 상태를 읽고 fetch를 호출한 뒤 loading, auth, list, form 상태를 갱신할 수 있습니다.

Fetch with store action flow

Business signal endpoint

Calling generated fetch

비즈니스 규칙은 service에 둡니다. 클라이언트 store는 폼 상태를 모으고 fetch를 호출하고 UI 상태를 갱신하는 역할을 맡으며, 비밀번호/권한/재고/결제 규칙을 중복 구현하지 않습니다.

생성된 헬퍼 요약

Akan은 @apps/<app>/client에서 앱 전용 헬퍼를 제공합니다. 화면 구조, st, fetch를 이해하고 나면 이 헬퍼들이 UI 작업의 일상적인 진입점이 됩니다.

함께 쓰이는 방식

하나의 page는 보통 usePage로 route와 language context를 읽고, Model.*에서 도메인 UI 조각을 가져오며, 브라우저 상태는 st로 다루고, 사용자 액션이 서버 비즈니스 응답을 필요로 할 때 fetch를 호출합니다.

usePage

params, l, page context

Model.*

Unit, View, Edit, Zone

state, derived, actions

fetch

endpoint calls

st: 생성된 hook과 action으로 클라이언트 상태를 읽고 변경합니다.

fetch: 생성된 endpoint를 호출하거나 page와 zone에 필요한 초기 데이터를 준비합니다.

Model.*: 각 도메인에서 Unit, View, Edit, Zone, Util 컴포넌트를 찾는 예측 가능한 진입점입니다.

usePage: 비즈니스 화면에서 언어, params, page context를 사용할 수 있게 합니다.

다국어

Akan page는 보통 usePage에서 language helper를 가져오고, l("model.dictKey") 방식으로 dictionary key를 렌더링합니다. 이렇게 하면 UI 문구를 컴포넌트 곳곳에 직접 흩뿌리지 않고 각 도메인 dictionary 가까이에 둘 수 있습니다.

문구를 한 곳에 선언

dictionary 파일은 도메인별 영어/한국어 문구를 보관합니다.

user.dictionary.ts

UI에서 key 사용

컴포넌트는 하드코딩 문구 대신 l("user.signWithGoogle")를 렌더링합니다.

l("user.signWithGoogle")

클라이언트 간 공유

고객, 관리자, 파트너, 모바일 화면이 같은 비즈니스 용어를 재사용할 수 있습니다.

web, admin, mobile

user.dictionary.ts

UserSigninButton.tsx