Skip to content

Architecture

Jump to bottom
Sonne edited this page Jan 16, 2026 · 1 revision

์ด ๋ฌธ์„œ๋Š” ์„ธ๋ชจ(Delta-front)์˜ ์ „์ฒด ๊ตฌ์กฐ์™€ ๋ชจ๋…ธ๋ ˆํฌ ๊ตฌ์„ฑ, web/app์˜ ์—ญํ•  ๋ถ„๋ฆฌ๋ฅผ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค.

1) Monorepo ๊ฐœ์š”

์„ธ๋ชจ๋Š” pnpm workspace ๊ธฐ๋ฐ˜ ๋ชจ๋…ธ๋ ˆํฌ๋กœ ์šด์˜ํ•ฉ๋‹ˆ๋‹ค.

  • apps/web : Next.js(Web) ์•ฑ (์‹ค์ œ ์„œ๋น„์Šค UI/๊ธฐ๋Šฅ์˜ ์ค‘์‹ฌ)
  • apps/app : React Native(App) ์•ฑ (ํ–ฅํ›„ WebView๋กœ web์„ ๊ฐ์‹ธ์„œ ์•ฑ ์ œ๊ณต)

๋ฃจํŠธ์—๋Š” ๊ณตํ†ต ๊ฐœ๋ฐœ ๋„๊ตฌ/์ •์ฑ…์ด ์œ„์น˜ํ•ฉ๋‹ˆ๋‹ค.

  • .github/ : GitHub Actions, ์ด์Šˆ/PR ํ…œํ”Œ๋ฆฟ ๋“ฑ
  • .husky/, commitlint.config.cjs : ์ปค๋ฐ‹/ํ›… ๊ทœ์น™
  • pnpm-workspace.yaml, pnpm-lock.yaml : ์›Œํฌ์ŠคํŽ˜์ด์Šค/๋ฝํŒŒ์ผ
  • package.json : workspace ์Šคํฌ๋ฆฝํŠธ ๋ฐ ์—”์ง„(Node/pnpm) ๊ด€๋ฆฌ

2) apps/web ๊ตฌ์กฐ (pages + shared)

apps/web/src๋Š” ํฌ๊ฒŒ ๋‘ ์ถ•์œผ๋กœ ๋‚˜๋‰ฉ๋‹ˆ๋‹ค.

  • src/app : ํŽ˜์ด์ง€(๋ผ์šฐํŠธ) ๋‹จ์œ„ ์ฝ”๋“œ (Next App Router)
  • src/shared : ๊ณตํ†ต ๋ ˆ์ด์–ด (์žฌ์‚ฌ์šฉ ์ปดํฌ๋„ŒํŠธ/์Šคํƒ€์ผ/์œ ํ‹ธ/API ๋“ฑ)

๐Ÿ“ Directory Map

  • apps/web/src/app/

    • ์‹ค์ œ ๋ผ์šฐํŠธ ํด๋”๋“ค: (home), graph, login, my, oauth, wrong ...
    • layout.tsx : ์ „์—ญ ๋ ˆ์ด์•„์›ƒ(HTML/Body/Theme/Provider ๋ž˜ํ•‘)
    • client-shell.tsx : ํด๋ผ์ด์–ธํŠธ ์ „์šฉ ์…ธ(์Šคํ”Œ๋ž˜์‹œ, AppBar, BottomNav ๋“ฑ)

  • apps/web/src/shared/

    • apis/ : axios ๊ธฐ๋ฐ˜ API ๋ชจ๋“ˆ + TanStack Query ํ›…
    • components/ : ๊ณตํ†ต UI ์ปดํฌ๋„ŒํŠธ(๋””์ž์ธ ์‹œ์Šคํ…œ ํฌํ•จ)
    • styles/ : Vanilla Extract ํ† ํฐ/ํƒ€์ดํฌ/ํ…Œ๋งˆ
    • constants/ : ๋ผ์šฐํŠธ, ํ‚ค, ์ƒ์ˆ˜
    • hooks/ : ๊ณตํ†ต ํ›…
    • utils/ : ์œ ํ‹ธ ํ•จ์ˆ˜
    • assets/ : ์ด๋ฏธ์ง€/Lottie/SVG sprite ๋“ฑ
    • types/ : ๊ณตํ†ต ํƒ€์ž…

  • apps/web/src/stories/

    • Storybook ์Šคํ† ๋ฆฌ(๋ฌธ์„œ/์‹œ๊ฐ ํ…Œ์ŠคํŠธ)

3) โ€œํŽ˜์ด์ง€๋Š” ์–‡๊ฒŒ, shared๋Š” ๋‘๊ป๊ฒŒโ€

๊ธฐ๋ณธ ๋ฐฉํ–ฅ์€ ์•„๋ž˜์ฒ˜๋Ÿผ ๊ฐ€์ ธ๊ฐ‘๋‹ˆ๋‹ค.

  • src/app/* : ๋ผ์šฐํŒ…/๋ฐ์ดํ„ฐ ๋ฐ”์ธ๋”ฉ/ํŽ˜์ด์ง€ ์กฐ๋ฆฝ ์—ญํ•  (์–‡๊ฒŒ)
  • src/shared/* : UI/์ƒํƒœ/์œ ํ‹ธ/๋ฐ์ดํ„ฐ fetching์˜ ์žฌ์‚ฌ์šฉ ๋กœ์ง (๋‘๊ป๊ฒŒ)

์ฆ‰, ๋„๋ฉ”์ธ ๋กœ์งยทUI ์žฌ์‚ฌ์šฉ์ด ๊ฐ€๋Šฅํ•˜๋ฉด shared๋กœ ์˜ฌ๋ฆฌ๋Š” ๊ฒƒ์„ ๊ธฐ๋ณธ์œผ๋กœ ํ•ฉ๋‹ˆ๋‹ค.

4) Provider / Layout ๊ตฌ์„ฑ ํ๋ฆ„

์ „์—ญ ์—”ํŠธ๋ฆฌ ๊ตฌ์„ฑ์€ ์•„๋ž˜์™€ ๊ฐ™์Šต๋‹ˆ๋‹ค.

  • app/layout.tsx

    • <html className={theme}>
    • <SvgSpriteInjector />
    • <ClientShell>{children}</ClientShell> (Suspense ์•„๋ž˜)

  • client-shell.tsx (Client Component)

    • QueryProvider (TanStack Query)
    • Splash (์ดˆ๊ธฐ UX)
    • AppBarGate (๋ผ์šฐํŠธ ๊ธฐ๋ฐ˜ AppBar ์ œ์–ด)
    • {children} (page)
    • BottomNav, FabButton

5) apps/app์—์„œ WebView๋กœ ๊ฐ์‹ธ๋Š” ๊ตฌ์กฐ

ํ–ฅํ›„ ์•ฑ ๋ฐฐํฌ๋ฅผ ์œ„ํ•ด apps/app์€ RN WebView ์ปจํ…Œ์ด๋„ˆ ์—ญํ• ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค.

  • RN ์•ฑ์€ ์ตœ์†Œํ•œ์˜ ๋„ค์ดํ‹ฐ๋ธŒ UI(๊ถŒํ•œ, ๋”ฅ๋งํฌ, ํ‘ธ์‹œ ๋“ฑ) + WebView๋ฅผ ์ œ๊ณต
  • ์‹ค์ œ ํ™”๋ฉด/๊ธฐ๋Šฅ์€ apps/web์ด ๋‹ด๋‹น
  • ๋„ค์ดํ‹ฐ๋ธŒ โ†” ์›น ํ†ต์‹ ์ด ํ•„์š”ํ•˜๋ฉด
    • postMessage / onMessage
    • ๋”ฅ๋งํฌ ์Šคํ‚ค๋งˆ
    • ํ† ํฐ ๋ธŒ๋ฆฟ์ง€ ๊ฐ™์€ ์ „๋žต์œผ๋กœ ํ™•์žฅํ•ฉ๋‹ˆ๋‹ค.
image

Delta-front Wiki
์„ธ๋ชจ ยท ๋‚˜๋งŒ์˜ ์ˆ˜ํ•™ ์˜ค๋‹ต๋…ธํŠธ

Home ยท CI/CD ยท Coding Convention ยท Troubleshooting

image

๐Ÿ ์‹œ์ž‘ํ•˜๊ธฐ

๐Ÿ—๏ธ ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ

๐ŸŽจ UI ยท ๋””์ž์ธ ์‹œ์Šคํ…œ

๐Ÿง  ๊ธฐ๋Šฅ ยท ๋„๋ฉ”์ธ

โš™๏ธ ์šด์˜ ยท ํ”„๋กœ์„ธ์Šค

๐Ÿ“DOCS

Clone this wiki locally