Core SDK (UI-agnostic)

This core/ module isolates domain logic from any view library. It exposes a small API you can plug into React, Vue, vanilla, or any renderer, similar to Sendbird's approach of providing a renderer-agnostic SDK.

Quick start (Sendbird-style facade)

import { createSdk, useScenes } from '@archisketch/avo-core';

const sdk = createSdk();
await sdk.scenes.load();
sdk.scenes.create(file);
sdk.finishes.applyToSelection(productId);

// React 컴포넌트에서 상태 구독
const scenes = useScenes(sdk);

createSdk()는 기본 어댑터를 적용한 뒤 Scenes, selection, finishes 등 상위 시나리오를 한 번에 제공합니다. React에서는 useSyncExternalStore 기반 헬퍼(useScenes, useCurrentSceneId)로 바로 상태를 구독할 수 있습니다.

Advanced (Internal)

저수준 CoreAPI, 포트/서비스, getCore() 등은 @archisketch/avo-core/internal 경로에 모았습니다. 신규 개발에는 파사드(createSdk)를 우선 사용하고, 레거시 호환이나 커스텀 어댑터 구성 시에만 내부 경로를 참고하세요.

Architecture

• Hexagonal (Ports & Adapters): core defines ports (ScenesPort, TransportPort, StoragePort, LoggerPort). Adapters implement these for different environments.
• Minimal state store: framework-free store (createStore) with getState/setState/subscribe for easy integration with any UI.
• Services: ScenesService orchestrates use-cases (load, create, select scene) using ports.
• Facade: 로우레벨 createCoreClient 외에 고수준 createSdk()를 제공해 빠른 온보딩을 돕습니다.

Using with current code (no changes)

Prefer the adapter that wraps the current scene APIs:

import { createCoreClient } from '@/core';
import { createExistingScenesAdapter } from '@/core/adapters/scenes/from-existing';

const core = createCoreClient({
  scenes: createExistingScenesAdapter(),
});

await core.scenes.load();
const unsub = core.state.subscribe((s) => console.log('Selected', s.currentSceneId));

Class vs Functional API (trade-offs)

• Class (Sendbird-style)

  • Pros: intuitive instance lifecycle, encapsulated state, easy namespacing, good DX for OOP users.
  • Cons: harder tree-shaking, inheritance can overfit, hidden mutable state if misused, mocking sometimes heavier.

• Functional Factory (this repo also provides)

  • Pros: better tree-shaking, composable, easy to unit test and mock, favors explicit dependency injection.
  • Cons: need to thread context/ports explicitly, can feel verbose without a facade, no classical inheritance.

Recommendation: expose both. Keep internals functional with DI, and provide a small class facade for ergonomics.

Folders

• ports/: interfaces for infra dependencies
• adapters/: bridges to concrete envs (e.g., current scene APIs)
• state/: tiny framework-agnostic store
• services/: business use-cases
• types/: pure domain types
• client.ts: 저수준 CoreAPI 팩토리 (internal 경로를 통해 접근)
• sdk.ts: Sendbird 스타일 상위 파사드
• sdk-react.ts: React에서 사용할 수 있는 구독 헬퍼

Next steps

• Add auth/session port if needed.
• Add command/query separation if flows grow complex.
• Consider a finite-state machine (XState-like) for complex upload flows.
• Move domain types from src/entities/* into core/types when ready (to complete the separation).

Architecture Diagram

상세 아키텍처 다이어그램은 docs/ARCHITECTURE.md를 참고하세요.