한 번 작성하고 어디든 배포

왜 우리는 하나의 비즈니스를 구현하기 위해 쪼개진 여러 프로젝트를 만들어야 하는 걸까요?

백엔드, 프론트엔드, 앱, 데이터베이스, 배포를 위해 같은 비즈니스 의도를 따로 설명하는 것은 혼란스럽고 비효율적인 것 아닐까요? 하나의 정의가 모든 surface로 흐를 수는 없을까요?

Akan.js는 비즈니스 정의가 web, app-oriented client surface, server runtime, data contract, deployment artifact의 단일 기준이 되는 풀스택 TypeScript 프레임워크입니다.

TypeScript

page, domain module, signal, service, store, UI를 비즈니스 정의로 한 번 작성합니다.

→

Akan Runtime

BunAkanAppGateway

Page

파일 라우팅 기반 web 및 app-oriented client surface.

Server

service, signal, API traffic, realtime traffic, background work.

Data

SQLitelibSQLPostgresRedis

하나의 컨벤션 기반 workspace가 runtime surface, data contract, generated artifact, deployable package를 만들어냅니다.

타입 안전한 하나의 비즈니스 정의에서 출발하면 Akan 컨벤션이 page, API contract, service, store, schema, runtime surface까지 의도를 이어줍니다.

이를 통해 다양한 플랫폼을 붙이는 일보다 고객이 경험할 제품을 설계하는 데 집중할 수 있습니다. 같은 명료함은 에이전트가 안전하게 확장할 수 있는 예측 가능한 구조도 제공합니다.

Akan.js는 다음의 배경 기술들을 매끄럽게 통합해 애플리케이션이 하나의 확장 가능한 시스템으로 성장하도록 돕습니다.

웹/모바일:

서버:

테스팅:

배포:

개발자를 비즈니스맨으로

Akan.js는 기술적인 배관 코드를 최소화하고, 비즈니스 로직을 표현하는 데 집중할 수 있도록 도와줍니다.

또한, 애플리케이션을 구축하기 위한 편의 기능과 설치 가능한 라이브러리를 제공하여 검증된 비즈니스 패턴을 반복 구현하지 않고 재사용할 수 있게 합니다.

이는 에이전틱 코딩 시대에 더욱 중요합니다. 비즈니스 의도가 놓일 자리가 분명하고 나머지 배치가 컨벤션으로 정해져 있을 때, 에이전트는 더 좋은 코드를 작성할 수 있습니다.

워크스페이스 (모노레포)

Akan.js는 monorepo 구조를 기본으로 합니다. 하나의 조직(팀)은 하나의 레포지토리(workspace) 위에서 여러 앱과 공통 라이브러리를 개발하며, 앱 실행부터 production build, library 개발, package 관리까지 모두 workspace root에서 실행하고 운영합니다.

Akan Workspace

apps

libs

appA

appB

appC

libA

libB

appA는 libA를 사용

appB는 libA와 libB를 사용

appC는 libB를 사용

코드 비중

20%

apps

80%

libs

앱(apps): 독립적으로 배포될 수 있는 제품 surface입니다. 앱은 page, runtime entry, app configuration, asset, 앱 전용 domain code를 가집니다.

공통 라이브러리(libs): 여러 앱이 공유하는 재사용 가능한 비즈니스 및 유틸리티 모듈입니다. 인증, 파일, 결제, 알림, 채팅, 관리자 기능, 도메인 모듈 등을 이곳에 두고 안전하게 재사용할 수 있습니다.

처음 `akan create-workspace`를 진행하면, 기본적으로 shared, util 라이브러리가 설치되고, 이는 공통 라이브러리로서 모든 앱에서 사용할 수 있습니다.

생성한 내 애플리케이션(e.g. myapp)에서 서버 로직, 도메인 모듈, 클라이언트 로직, 컴포넌트 등의 공통 라이브러리를 사용할 수 있습니다. 예를 들면, shared 라이브러리에서는 관리자페이지와 파일 업로드 도구 등을 제공합니다.

80:20 규칙

건강하게 유지되는 워크스페이스는 약 80%의 코드가 공통 라이브러리로 공유되고, 20%의 코드가 각 앱에 특화되어 운영되는 구조를 권장합니다.

하지만 규칙을 지키려고 노력하지 않아도 됩니다. 당신이 마음을 담아 워크스페이스를 유지보수 하는 과정에서 자연스럽게 비율이 맞추어질 것입니다.

워크스페이스 파일 구조

앱과 라이브러리는 예측 가능한 구조를 공유합니다. 그래서 page, domain module, asset, runtime entry가 어디에 있는지 쉽게 찾을 수 있습니다.

앱은 main.ts에서 AkanApp으로 실행되고, 사용자에게 전달되는 route는 page/ 아래에 선언합니다. 도메인 모듈은 lib/ 아래에 위치하며 apps와 libs 어디에서든 공유할 수 있습니다.

처음부터 모든 파일 규칙을 이해할 필요는 없습니다. 먼저 내가 바꾸려는 코드가 사용자에게 전달되는 page인지, 비즈니스 domain module인지, 재사용 UI인지, 앱 runtime configuration인지 파악하면 됩니다.

워크스페이스 전체에서 같은 컨벤션이 반복되기 때문에 사람과 에이전트 모두 낯선 코드를 처음부터 추측하지 않고 탐색할 수 있습니다.

Application or Library Anatomy

serverclientshared

Domain modules

Interface

lib/product/product.constant.ts · dictionary.ts · signal.ts

Data and service

lib/product/product.document.ts · service.ts

UI and state

lib/product/product.store.ts · Product.Template.tsx · Unit.tsx · View.tsx · Zone.tsx

Scalar modules

lib/__scalar/fileMeta/fileMeta.constant.ts

Service utilities

srvkit/account.ts · srvkit/guards.ts

UI and webkit

ui/Field.tsx · webkit/useFirebaseMessaging.tsx

page/

앱 route

main.ts

runtime entry

base/ · common/

순수 공유 로직

public/ · private/

정적 asset

파일 규칙을 따르면 애플리케이션이 커져도 확장 가능하고 재사용 가능한 구조를 유지할 수 있습니다. 중요한 질문은 어떤 프레임워크 레이어와 씨름할지가 아니라, 어떤 비즈니스 의도를 표현하고 있으며 그 의도가 어디에 위치해야 하는지입니다.

예를 들어 패스워드 기반 로그인 기능에서는 입력 폼은 page 또는 UI component 가까이에, 비밀번호 규칙은 공유 domain definition 가까이에, 저장과 보안 동작은 domain module의 service layer에 두는 식입니다.

동료들과 한몸처럼

Akan.js는 엄격한 파일 규칙을 제공하여 사람과 에이전트가 같은 형태로 기능을 구현할 수 있도록 돕습니다.

이를 통해 개발자들은 한몸처럼 협업할 수 있고, 동료는 긴 러닝커브 없이 작업을 이어받을 수 있으며, 코딩 에이전트는 추측해야 할 아키텍처 선택지를 줄일 수 있습니다.

워크스페이스에서 가장 많이 작업하는 것은 두 가지입니다. 1) 사용자에게 전달되는 page를 작성하는 것, 2) 비즈니스 개념을 표현하는 domain module을 작성하는 것입니다. Akan은 두 작업 모두에 명확한 컨벤션을 제공합니다.

페이지 파일 규칙 - 파일 기반 라우팅

페이지는 URL 경로에 맞추어 사용자에게 전달되는 route와 layout을 구현하는 파일입니다. Akan은 page/ 아래의 폴더 구조를 스캔하고, 생성된 route artifact를 Akan runtime을 통해 제공합니다.

도메인 모듈 파일 규칙

도메인 모듈은 회원 관리, 주문, 결제, 프로젝트처럼 비즈니스에서 하나의 도메인을 차지하는 개념의 표현입니다. Akan은 해당 개념의 데이터 구조, 서비스 동작, API contract, 상태, UI를 하나의 예측 가능한 폴더 안에서 정렬합니다.

하나의 도메인은 복합적인 유기체처럼 활동합니다. constant.ts의 스키마 정의에서 Zone.tsx의 통합 컴포넌트까지 관련 변경이 가까운 곳에 머뭅니다. 이를 통해 백엔드-프론트엔드 간의 버전 격차, 비즈니스 로직 변경 시 발생하는 문제, 에이전트가 변경 전에 탐색해야 하는 위치를 줄일 수 있습니다.

누구에게 적합한가요?

Akan은 고객에게 빠르게 제품 수준의 가치를 전달하고 싶은 개발자와 팀에게 적합합니다.

살아있는 제품은 지속적으로 관리되고 운영되어야 합니다. Akan.js는 한 명의 개발자가 여러 프로젝트를 동시에 운영하고, 여러 개발자가 하나의 프로젝트를 한 몸처럼 협업하며, 에이전트도 같은 컨벤션 안에서 기여할 수 있는 환경을 제공합니다.

프레임워크는 언제나 trade-off를 가집니다. 단순하게 사용할 수 있다면 고도화가 어려울 수 있고, 다양성을 포용하면 협업이 어려울 수 있습니다. 우리는 이러한 문제에 대해 다음과 같은 부분에 집중합니다.

우리가 집중하는 부분

✅ 비즈니스를 표현하기 위한 추상화된 인터페이스

✅ 제품 수준의 퀄리티를 위한 최신 트렌드 기술의 검토, 안정화된 형태의 지속적 반영

✅ 엄격하고 단일화된 규칙을 통한 일관된 작업방식과 모범 사례 제공

✅ 의도가 놓일 자리가 분명한 에이전트 친화적 코드베이스

우리가 집중하지 않는 부분

❌ 비즈니스와 관련없는 불필요한 기술적 세부사항 표현

❌ 불안정한 기술 반영과 불필요한 최적화

❌ 다양한 작업 방식에 대한 복수 허용

역순으로 작업하기

프로그래밍은 우리와 고객의 삶을 효율화하고 긴밀하게 연결해 비즈니스 가치를 창출하는 것입니다. 문제를 정의하고, 빠르게 Akan.js를 통해 제품 수준의 해결책을 만들어내어 손쉽게 고객에게 전달하세요!

언제든 Akan.js는 여러분의 프로젝트를 지원하고, 목소리를 듣는 중입니다. 만약 궁금한 점이 있다면, GitHub에 이슈를 남겨주세요. 당신은 고객을 위해 일할 때, 우리는 당신을 위해 일합니다.