아키텍처 · JB Silver Connect

구성도

[고객 앱 www]   [창구 화면 teller]   [대기 화면 display]
      \               |                  /
       \              |                 /     (Next.js 세 앱, REST 호출)
        +------ FastAPI 백엔드 jb ------+
                /api/v1/{branch, chat, queue, reservation, corporate}
                       |
        컨텍스트별 domain <- app <- adapter (+ dependencies 조립)
                       |
        core: LLM(Gemini → Groq → Mock) · 계좌/고객 Mock · shared_kernel

(근거: jb/main.py, jb/core/di.py, 각 앱의 package.json·src/lib/api.ts)

헥사고날 레이어

백엔드는 헥사고날(Ports & Adapters) 구조이고, 의존은 항상 바깥에서 안쪽으로만 향합니다. (근거: jb/ARCHITECTURE.md)

레이어	위치	책임	import 가능 대상
domain	`apps/<컨텍스트>/domain/`	엔티티, 값 객체, 이벤트, 도메인 서비스	`shared_kernel` 만
app	`apps/<컨텍스트>/app/`	유스케이스, 입출력 포트, DTO	`domain`, `core.ports`, `shared_kernel`
adapter	`apps/<컨텍스트>/adapter/`	FastAPI 라우터, 스키마, Mock·외부 연동 구현	`app`, `domain`
dependencies	`apps/<컨텍스트>/dependencies/`	의존성 조립(조립 루트)	모두
core	`core/`	공용 포트와 LLM·계좌·고객 어댑터	`shared_kernel`
shared_kernel	`shared_kernel/`	공용 값 객체(금액, 사용자 ID, 창구 종류)	없음

백엔드 컨텍스트 5개

컨텍스트	하는 일	대표 엔드포인트	근거
`branch`	가까운 지점 조회(거리순)	`POST /branch/nearby`	`jb/apps/branch`
`chat`	AI 대화, 직원용 요약 카드 전달·조회	`POST /chat/message`, `POST /chat/handoff`, `GET /chat/handoffs`	`chat_router.py`
`queue`	창구 대기열, 도착 인증, 호출, 만료	`GET /queue/entries`, `POST …/arrive`, `POST …/call`	`queue_router.py`
`reservation`	번호표 발급·조회·취소	`POST·GET /reservation/tickets`	`reservation_router.py`
`corporate`	법인 사무 필요 서류·비용·발급 기관 안내	`POST /corporate/guidance`	`corporate_router.py`

모든 라우터는 /api/v1 아래에 등록됩니다. (근거: jb/main.py)

Mock 으로 데모하고 실구현으로 교체

jb/ARCHITECTURE.md 는 「데모 단계는 Mock 어댑터로 동작하며, 운영 전환 시 Mock 만 실구현으로 교체한다」고 설명합니다. 코드에서 확인되는 사례는 다음과 같습니다.

LLM: Gemini → Groq → Mock 순서로 시도하고, 키가 없으면 다음 순위로 넘어갑니다. (근거: jb/core/di.py)
지점 검색: Naver → Mock 순서로 시도하고, 키가 없거나 호출이 실패하면 Mock 데이터를 씁니다. (근거: branch_provider.py)
계좌와 고객 정보: Mock 구현(MockAccountQuery, MockCustomerDirectory). (근거: jb/core/di.py)
예약·대기열 저장: 메모리 저장소(InMemory…Repository). 데이터베이스는 연결하지 않았습니다. (근거: 커밋 4d9903c, 01693b9)

레이어 규칙을 도구로 강제

setup.cfg 의 import-linter 계약이 adapter > app > domain 방향과 shared_kernel 의 독립성을 검사합니다. 실행은 .venv/bin/lint-imports 입니다. (근거: setup.cfg, jb/ARCHITECTURE.md)

테스트는 jb/tests 에 도메인과 유스케이스 단위로 있습니다. 대기열 상태 전이, 창구 종류, 예약 취소, 법인 안내, 고객 디렉터리를 다룹니다. (근거: jb/tests/ 파일 목록)

알아 둘 점

jb/ARCHITECTURE.md 는 첫 커밋 시점의 문서입니다. 6개 컨텍스트(savings, reservation, phishing, briefing, branch, report)를 설명하지만, 이후 커밋 9215dfb 에서 savings·phishing·briefing·report 가 삭제되고 queue·corporate 가 추가되었습니다. 이 페이지는 최종 코드를 기준으로 썼습니다.