resumate 개발일지 02. 기술 스택 선택 이유

┌─────────────────────────────────────────────────────────┐
│  macOS 데스크탑 앱                                        │
│                                                          │
│  [Tauri v2 쉘 — Rust]                                    │
│   ├── WebView "dock"    ← React + Vite (캐릭터 독)        │
│   └── WebView "main"    ← React + Vite (작업 창)         │
│                │                                         │
│                │ HTTP / SSE                              │
│                ▼                                         │
│  [Sidecar — Bun + Hono]                                  │
│                │                                         │
│                │ stdin/stdout                            │
│                ▼                                         │
│  [Claude CLI]                                            │
└─────────────────────────────────────────────────────────┘
 
프론트엔드:   React 18, Zustand v5, Tailwind CSS v4
빌드 도구:    Vite 6
백엔드 쉘:   Rust (Tauri v2), SQLite
사이드카:    Bun, Hono, TypeScript strict
AI 엔진:     Claude CLI (Anthropic)

// tauri.conf.json
{
  "label": "dock",
  "transparent": true,
  "decorations": false,
  "alwaysOnTop": true,
  "width": 500,
  "height": 300
}

// src-tauri/src/lib.rs
tauri::Builder::default()
    .plugin(tauri_plugin_sql::Builder::default().build())
    .invoke_handler(tauri::generate_handler![find_free_port])
    .run(tauri::generate_context!())

// src-tauri/src/lib.rs — 핵심 로직 전체
#[tauri::command]
async fn find_free_port() -> Result<u16, String> {
    // 사용 가능한 포트를 찾아서 사이드카 서버 실행
    let listener = TcpListener::bind("127.0.0.1:0")?;
    Ok(listener.local_addr()?.port())
}

// src-tauri/src/ipc.rs — 등록되지 않은 코드
async fn fs_read(path: String) -> Result<String, String> { ... }
async fn shell_exec(cmd: String, args: Vec<String>) -> Result<...> { ... }

// src/main.tsx — 창 라벨에 따라 다른 컴포넌트 렌더링
const label = await getCurrentWebviewWindow().label;
const root = createRoot(document.getElementById("root")!);
 
if (label === "dock") {
  root.render(<CharacterDock />);
} else {
  root.render(<App />);
}

// vite.config.ts
export default defineConfig({
  plugins: [
    react(),           // @vitejs/plugin-react — React Fast Refresh
    tailwindcss(),     // @tailwindcss/vite — Tailwind v4 네이티브 통합
  ],
  clearScreen: false,  // Tauri 로그가 지워지지 않도록
  server: {
    port: 1420,        // Tauri가 기대하는 포트 (tauri.conf.json과 일치)
    strictPort: true,  // 포트 충돌 시 에러 (조용히 다른 포트로 넘어가지 않음)
    watch: {
      ignored: ["**/.omc/**"],  // omc 세션 파일 변경 시 HMR 무시
    }
  },
  envPrefix: ["VITE_", "TAURI_"],  // Tauri 환경변수도 프론트에서 접근 가능
});

import tailwindcss from "@tailwindcss/vite";
// 설정 파일 없이 이 한 줄로 끝

// src/store/agentStore.ts — AI 도메인 상태
const useAgentStore = create<AgentStore>((set, get) => ({
  activeCharacter: "nyx",
  conversations: { nyx: { messages: [] }, paws: { messages: [] }, echo: { messages: [] } },
  loading: { nyx: false, paws: false, echo: false },
  // 액션들...
}));
 
// src/store/workspaceStore.ts — UI/워크스페이스 상태
const useWorkspaceStore = create<WorkspaceStore>((set) => ({
  showFileTree: false,
  showTerminal: false,
  showWorkWindow: false,
  rootDir: null,
  selectedSkills: [],
  terminalOutput: [],
}));

// dock 창에서 activeCharacter를 "paws"로 바꿔도
// main 창의 Zustand 스토어는 여전히 "nyx"

// CharacterDock.tsx
await emit("character-clicked", { id: character.id });
 
// App.tsx
await listen("character-clicked", (event) => {
  setActiveCharacter(event.payload.id);  // main 창 스토어도 업데이트
});

{"type": "assistant", "message": {"content": [{"type": "text", "text": "안녕"}]}}
{"type": "tool_use", "name": "bash", "input": {"command": "ls"}}
{"type": "tool_result", "content": "file.txt"}
{"type": "result", "usage": {"input_tokens": 100, "output_tokens": 50}}

// sidecar/claude.ts
for await (const line of rl) {
  const event = JSON.parse(line);
  if (event.type === "assistant") {
    const text = event.message.content
      .filter(b => b.type === "text")
      .map(b => b.text).join("");
    res.write(`data: ${JSON.stringify({ type: "text", text })}\n\n`);
  }
}

// sidecar/index.ts — Hono 서버 전체 구조
const app = new Hono();
app.get("/health", (c) => c.json({ status: "ok" }));
app.get("/skills", (c) => c.json(getSkills()));
app.get("/list", (c) => c.json(listDirectory(c.req.query("path"))));
app.post("/chat", async (c) => {
  // SSE 스트림 반환
  return streamSSE(c, async (stream) => { ... });
});

// tsconfig.json (frontend)
{ "compilerOptions": { "strict": true } }
 
// sidecar/tsconfig.json
{ "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true } }

// src/store/agentStore.ts
export type CharacterId = "nyx" | "paws" | "echo";
 
// 이 타입 덕분에 오타나 잘못된 캐릭터 ID를 컴파일 타임에 잡는다
function handleClick(id: CharacterId) { ... }
handleClick("npc"); // 컴파일 에러!

/* 기존 v3: tailwind.config.js에 theme 설정 */
/* 새로운 v4: CSS 파일에 직접 */
@import "tailwindcss";
 
@theme {
  --color-brand: oklch(60% 0.2 260);
  --font-sans: "Pretendard", system-ui;
}

// src/lib/db.ts
const db = await Database.load("sqlite:resumate.db");
 
// conversations 테이블: 캐릭터별 대화 내용 저장
await db.execute(`CREATE TABLE IF NOT EXISTS conversations (
  character_id TEXT PRIMARY KEY,
  messages     TEXT NOT NULL DEFAULT '[]'
)`);

dock 창 (500×300, 투명, 항상 위)
  → 항상 화면에 떠 있는 캐릭터 위젯
  → 클릭해도 다른 앱이 가려지지 않음
 
main 창 (1280×800, 투명, 기본 숨김)
  → 실제 AI와 대화하는 작업 공간
  → 캐릭터 클릭 시에만 등장

// dock → main
await emit("character-clicked", { id: "nyx" });
await emit("window-state-changed", { visible: false });
 
// main → dock (없음 — main에서 dock으로 가는 이벤트는 미구현)

// sidecar/index.ts — Hono SSE
app.post("/chat", async (c) => {
  return streamSSE(c, async (stream) => {
    const abortController = new AbortController();
    c.req.raw.signal.addEventListener("abort", () => abortController.abort());
 
    await runAgentLoop(body, (event) => {
      stream.writeSSE({ data: JSON.stringify(event) });
    }, abortController.signal);
  });
});
 
// src/lib/sidecar.ts — 프론트엔드 SSE 파싱
const response = await fetch(`${BASE_URL}/chat`, { method: "POST", body, signal });
const reader = response.body!.getReader();
// ReadableStream을 읽으면서 SSE 이벤트 파싱

1. 공유 타입 패키지
   monorepo 구조에서 packages/shared-types를 만들어
   frontend와 sidecar가 같은 타입을 import
 
2. 상태 동기화 전략 선결
   멀티 창 앱이라면 처음부터 BroadcastChannel + Zustand 미들웨어
   또는 SQLite를 단일 진실 공급원으로 설계
 
3. CSP 활성화
   개발 초기부터 보안 정책을 켜두고 필요한 것만 허용
 
4. 사이드카 경로 동적 해결
   빌드 시 Claude 경로를 환경변수나 PATH 탐색으로 해결
 
5. 데이터 영속화 테스트
   저장/로드를 E2E 테스트로 커버해서 "아무도 안 부르는 함수" 버그 방지

React:               18.3.1
Vite:                6.x
Tailwind CSS:        4.x
Zustand:             5.x
Tauri:               2.x
Rust:                1.77.2+
Bun:                 (최신)
Hono:                4.12.9
TypeScript:          5.6.2
@react-three/fiber:  8.x
three.js:            0.160.0
dotlottie-react:     0.18.8