모바일 앱 아키텍처

Akan 모바일 앱은 Capacitor 네이티브 shell 안에서 실행되는 CSR 웹 클라이언트입니다. 제품 화면은 여전히 Akan page, UI, state, service 패턴으로 만들고, Capacitor가 네이티브 프로젝트, 앱 식별 정보, 스토어 패키지, 디바이스 브리지를 제공합니다.

Akan mobile architecture

하나의 UI 표면: 웹과 모바일은 같은 Akan page tree, client router, generated fetch 호출, dictionary, UI component를 공유합니다.

네이티브 shell 경계: 네이티브 코드는 패키징, signing, app capability, plugin linking, store 배포를 담당합니다.

공유 백엔드: Android, iOS, 웹 client는 같은 Akan service를 호출하고 auth, permission, database rule, app-level domain을 공유할 수 있습니다.

모바일 Target

모바일 target은 Akan 앱에서 만들어지는 하나의 네이티브 패키지입니다. 하나의 Akan 앱은 각 target이 서로 다른 basePath를 열도록 설정해 여러 모바일 패키지를 배포할 수 있고, 백엔드 모듈은 그대로 공유할 수 있습니다.

apps/myapp/akan.config.ts

패키지별로 app ID, 표시 이름, 진입 화면, 권한, 딥링크, 스토어 릴리즈 트랙이 다르면 target을 나누세요.

CSR 런타임

네이티브 shell 안에서 Akan은 CSR router와 모바일 page frame을 사용합니다. Page transition, safe area, navbar/bottom inset layer, keyboard accessory, page cache는 네이티브 UI를 다시 작성하지 않고 client runtime layer에서 처리됩니다.

page/store/product/[productId].tsx

transition: CSR page motion을 제어해 모바일 내비게이션이 네이티브 앱에 가깝게 느껴지도록 합니다.

safeArea: 노치, 홈 인디케이터, Android system bar 같은 OS 영역을 처리합니다.

topInset / bottomInset: navbar, tab, fixed action, keyboard accessory 같은 앱 chrome을 page content와 분리합니다.

네이티브 브리지

디바이스 기능은 Capacitor plugin을 통해 접근합니다. Akan은 앱 레벨 API를 작게 유지합니다. 필요한 네이티브 기능을 선언하고, 네이티브 프로젝트를 sync/build한 뒤 CSR 앱에서 해당 client hook 또는 plugin wrapper를 호출합니다.

Permissions: Permissions는 모바일 target이 사용하려는 네이티브 기능을 설명합니다.

Files: Firebase 설정 같은 네이티브 config 파일은 app 폴더에서 생성된 네이티브 프로젝트 경로로 복사됩니다.

Deep links: 네이티브 scheme, universal link, app link는 정규화된 route로 Akan CSR router에 들어옵니다.

Push notifications: Push 수신은 Firebase/FCM 설정을 사용하고, 클릭 라우팅은 표준 data.url 필드를 사용합니다.

구체적인 설정 절차는 Cheatsheet > 개발 > 모바일 문서를 참고하세요.

비즈니스 서비스

CSS와 스타일링