아키텍처 개요 (C4)
얼마집 시스템의 전체 구조를 C4 모델 로 그립니다. 개별 기능을 어떻게 구현하는지는 각 가이드 문서에 있고, 이 문서는 “우리 시스템이 무엇으로 이루어져 있고 무엇에 의존하는가” 하나만 답합니다. 설계 결정의 근거는 결정 기록(ADR)에 있습니다.
이 문서는 Level 1(System Context)·Level 2(Container)만 그립니다. Level 3(Component)·Level 4(Code)는 의도적으로 만들지 않습니다 —
packages/*가 38개이고 주 단위로 바뀌어서, 손으로 그린 컴포넌트 다이어그램은 그린 다음 주에 바로 거짓말이 됩니다. 그 층은 코드와 타입, 그리고 패키지 레퍼런스 문서가 대신합니다.
Level 1 — System Context
누가 얼마집을 쓰고, 얼마집이 무엇에 의존하는지.
여기서 꼭 알아야 할 것 하나: 조합·투표·총회·설문 같은 핵심 도메인 데이터는 이 레포에 없습니다. 별도 레포의 FastAPI 서버(api.howmuchhome.co)가 소유합니다. 이 모노레포는 그 위의 클라이언트 + 얇은 BFF입니다.
Level 2 — Container
모노레포 안에 무엇이 배포 단위로 존재하고, 서로/외부와 어떻게 통신하는지.
컨테이너 요약
| 컨테이너 | 배포 | 역할 |
|---|---|---|
apps/native-app | Expo (스토어 + 자체 호스팅 OTA) | iOS·Android 앱. 신규 화면의 기본 타깃 |
apps/app | Vercel · app.howmuchhome.co | 공개 웹, 공유 링크, native로 아직 이관되지 않은 웹뷰 화면 |
apps/dashboard | Vercel · dashboard.howmuchhome.co | 집행부 관리, 광고주 포털(/advertiser), 영업 데모(/demo), 결제 |
apps/api (front-api) | Vercel · front-api.howmuchhome.co | BFF. Neon DB 소유, AI 세무상담, OTA 매니페스트, 딥링크, 카페·뉴스 |
apps/short-link | Vercel | 단축 URL 리다이렉트 (Neon 직접 조회) |
apps/binzip · binzip-admin | Vercel | 빈집정비(철거) 지원사업 동의서 신청 웹 + 운영 어드민 |
apps/docs | Vercel | 이 문서 (Nextra) |
packages/* | 배포 없음 | 공유 라이브러리. 자세한 건 패키지 레퍼런스 참조 |
두 개의 백엔드
가장 자주 혼동되는 지점입니다. 클라이언트는 하나의 fetcher를 쓰지만 실제 목적지는 엔드포인트 정의의 server 값에 따라 갈립니다.
server: 'main' (기본값) | server: 'front' | |
|---|---|---|
| 대상 | 얼마집 코어 API (FastAPI, 다른 레포) | apps/api (Next.js, 이 레포) |
| prod 호스트 | api.howmuchhome.co | front-api.howmuchhome.co |
| URL 조합 | ${host}/api/${path} | ${host}/${path} (프리픽스 없음) |
| 데이터 소유 | 조합·투표·총회·설문·조합원 등 핵심 도메인 | Neon PG (딥링크·OTA·카페 부가·AI 상담 등) |
배선은 packages/api/fetcher/fetch.ts에 있고, 왜 이렇게 나뉘었는지는 ADR-0001에 있습니다.
그리지 않는 것 (의도적)
| 안 그림 | 이유 | 대신 볼 곳 |
|---|---|---|
| C4 Level 3 (Component) | packages/* 38개 · 주 단위 변경 → 즉시 노후화 | 타입 정의, 패키지 레퍼런스 |
| C4 Level 4 (Code) | 코드가 곧 사실 | 코드 |
| 화면별 플로우 | Funnel 문서가 이미 담당 | Funnel |
| 배포 파이프라인 상세 | 별도 문서가 이미 담당 | 빌드·배포, OTA |
문서를 화려하게 만드는 게 목적이 아닙니다. 유지 가능한 수준으로만 남깁니다.
갱신 트리거
아래에 해당할 때만 이 문서를 고치면 됩니다. 그 외에는 손대지 마세요.
apps/에 배포 단위가 추가·삭제될 때 → Level 2 + 컨테이너 요약 표- 새 외부 시스템에 의존하기 시작할 때 (신규 SaaS·백엔드) → Level 1, Level 2
- 클라이언트 → 백엔드 라우팅 규칙이 바뀔 때 → “두 개의 백엔드” 표
- 그 변경이 되돌리기 어렵거나 논쟁의 여지가 있었다면 → 이 문서만 고치지 말고 ADR도 한 장 남기세요