아키텍처 개요

Akan 아키텍처는 분리된 frontend, backend, mobile, infrastructure 체크리스트가 아니라 제품 동작에서 시작합니다. 고객이 화면을 보고, 액션을 수행하면, 비즈니스 규칙이 무엇이 일어나야 하는지 결정하고, 데이터가 바뀌며, 다른 클라이언트에 알림이 갈 수 있고, 같은 앱은 web, mobile, cloud, edge 환경으로 패키징될 수 있습니다.

핵심 철학

비즈니스 동작을 먼저 작성하고, API와 상태 연결 코드는 생성된 헬퍼로 줄입니다.

SSR web, CSR web, admin, partner, mobile 같은 여러 클라이언트 표면이 하나의 비즈니스 서비스 계층을 공유하게 합니다.

배포 형태는 제품 요구가 생긴 뒤 선택합니다. 먼저 local에서 시작하고, 이후 cloud, edge, hybrid로 확장합니다.

하나의 앱, 여러 표면

Akan은 하나의 화면만 가지는 제품보다 여러 표면을 가진 제품을 위해 설계되었습니다. 스토어 고객 페이지, 관리자 콘솔, 파트너 클라이언트, 모바일 앱, 엣지 장비 워크플로우는 서로 다른 인터페이스를 보여주면서 같은 규칙과 데이터를 공유할 수 있습니다.

표면 지도

UI surfaces: SSR page, CSR page, admin client, partner client, mobile CSR client입니다.

Client helpers: 생성된 fetch, st, Model, usePage helper가 화면을 비즈니스 동작에 연결합니다.

Shared business service: signal이 호출을 받고, service가 규칙을 결정하며, document가 저장 데이터를 처리합니다.

Runtime shape: 같은 제품은 local, cloud cluster, edge, mobile package 안에서 실행될 수 있습니다.

핵심은 모든 클라이언트를 똑같이 보이게 만드는 것이 아닙니다. 서로 다른 클라이언트가 각 사용자군에 맞는 워크플로우를 보여주면서도 같은 비즈니스 진실을 재사용하게 만드는 것입니다.

주요 런타임 대화

대부분의 Akan 기능은 인터페이스와 비즈니스 서비스 사이의 대화로 이해할 수 있습니다. 인터페이스는 유용한 콘텐츠를 보여주고 의도를 수집합니다. 비즈니스 서비스는 안전한 요청을 받고, 규칙을 판단하고, 데이터를 바꾸며, 필요하면 백그라운드나 실시간 후속 작업을 실행합니다.

사용자가 보고 행동: SSR은 첫 화면을 빠르게 보여주고, client component는 입력, 클릭, 필터, 채팅, 지도, 카메라, 로컬 상태를 처리합니다.

생성 헬퍼가 서비스 표면 호출: fetch는 signal endpoint를 호출하고, st는 클라이언트 상태를 관리하며, Model namespace는 모델 사용을 타입화하고, usePage는 i18n을 처리합니다.

Signal이 의도 라우팅: signal은 endpoint, slice, internal 작업을 호출 가능한 표면으로 노출합니다. 유효한 작업을 service에 보내기 전에 경계를 적용합니다.

Service가 비즈니스 판단: service는 규칙, 저장 데이터, 외부 API, 의존성 주입, 백그라운드 작업, 실시간 발행을 조율합니다.

Document와 runtime이 루프 완성: document는 schema, query, sort, method, static을 정의합니다. runtime과 infra는 작업이 어디로 도착하고 어디서 실행될지 결정합니다.

아키텍처 영역

세부 아키텍처 문서는 각 영역을 더 깊게 설명합니다. 이 overview는 지도를 작게 유지합니다. 각 영역은 서로 다른 종류의 결정을 담당하고, 그 결정들이 올바른 위치에 있을 때 제품 구조가 명확해집니다.

UI 아키텍처: 첫 화면, SSR, 렌더링 경계, client component, st, fetch, generated helper, i18n, client target을 설명합니다.비즈니스 서비스 아키텍처: signal, service, document, request/response 작업, cron/background 작업, 리포트 생성, 실시간 시나리오를 설명합니다.인프라 아키텍처: local, cloud cluster, edge, master, traffic path, database mode, growth stage를 설명합니다.모바일 아키텍처: Capacitor 안에서 실행되는 CSR web, multi-client basePath target, 로컬 CSR 테스트, pageConfig, Android/iOS 패키징을 설명합니다.스타일링 기반: Tailwind CSS, DaisyUI, 디자인 시스템 사고, 테마 선언, 폰트 선언을 설명합니다.

아키텍처 문서 읽는 순서

무언가를 만들기 전에 모든 아키텍처 문서를 먼저 읽을 필요는 없습니다. 지금 마주한 결정에서 시작하고, 그 결정을 담당하는 페이지로 이동하면 됩니다.

첫 화면이나 클라이언트 동작을 설계해야 한다 → UI Architecture

서버 규칙, API, queue, cron, realtime 작업이 필요하다 → Business Service Architecture

local, cloud, edge, database, deployment 형태를 골라야 한다 → Infra Architecture

CSR 클라이언트를 Android 또는 iOS로 패키징해야 한다 → Mobile Architecture

일관된 컴포넌트 스타일, 테마, 폰트 규칙이 필요하다 → Styling Foundation