고객이 키오스크에서 주문 버튼을 누르면, 그 버튼 하나가 네 가지 일을 해야 합니다. 망고가 떨어졌으면 주문을 거절하고, 주문을 기록하고, 지금 영수증을 돌려주고, 고객이 돌아서기 전에 주방 화면에 티켓을 띄우는 일입니다.

어느 것도 화면을 그리는 일이 아닙니다. 이 일들을 합쳐 비즈니스 서비스라고 부릅니다. 요청이 부탁하는 액션, 그 뒤의 비즈니스 규칙, 액션이 시작하는 백그라운드 작업, 그리고 다른 화면에 알려야 하는 변경입니다.

모든 모듈은 이 일을 같은 파일 세 개로 나누고, 나누는 기준은 바뀌지 않습니다. 요청은 API 포트에 도착해 세 파일을 차례로 지나갑니다:

파일마다 답하는 질문이 하나씩 있고, 그 질문에만 답합니다:

카운터에서 일어나는 실제 액션 두 개를 세 파일에 걸쳐 따라가 봅니다:

판단은 service에 있습니다. 주문이 두 번째 모듈인 inventory와 만나는 자리이고, 두 document를 모두 불러온 뒤에야 저장하는 자리입니다:

관리자의 몫은 거울상입니다. 같은 파일 세 개, 다른 guard, 그리고 상태 기계가 없습니다. 오늘 재고 보충은 admin이 요청하면 언제든 허용되기 때문입니다. 그 signal은 아래 '호출에 경계 두기'에 나옵니다.

모델의 signal 파일은 클래스 셋을 내보내고, 둘이 비어 있더라도 모든 모듈이 셋을 모두 선언합니다. 어느 것을 쓸지는 하나로 정해집니다. 누가 그 호출을 시작하는가입니다.

클래스 목록이 아니라 제품 동작에서 시작하세요. 사용자가 지금 답을 받아야 하는지, 열린 연결로 대화해야 하는지, 여러 화면에 알려야 하는지, 나중에 끝나는 작업인지에 따라 고릅니다.

모든 endpoint는 option 객체를 받고, guards는 그중 첫 번째 필드일 뿐입니다. 나머지 필드는 호출이 어떻게 동작할지 정합니다. 얼마나 오래 걸려도 되는지, 응답을 재사용해도 되는지, 에이전트에게 보이는지입니다.

아래는 관리자의 몫입니다:

호출자가 기다리지 않는 작업도 있습니다. 아이스크림이 녹으라고 버튼을 누르는 사람도, 지난밤 주문을 정리해 달라고 요청하는 사람도 없습니다. 이런 작업은 Internal 클래스에 두고, 서버가 스스로 시작합니다:

둘 다 internal signal이고, 이를 실제로 돌리는 것은 백그라운드 작업을 맡는 서버 프로세스인 batch replica입니다.

같은 파일에 pubsub room도 하나 생깁니다. 아무도 호출하지 않는 endpoint입니다. 그곳에 publish하는 것은 서버이기 때문입니다:

주문이 processing으로 넘어갈 때 주방 화면은 이미 열려 있고, 아무도 새로고침을 누르지 않습니다. 그래서 service가 저장된 주문을 새 상태 이름의 room으로 publish하고, 그 상태를 구독하는 화면마다 티켓이 덧붙습니다.

service는 주입받은 필드로 자기 signal에 닿고, 저장 바로 뒤에 publish합니다:

service는 필요한 것을 직접 만들지 않습니다. serve()의 builder 인자에 적어 두면, handler가 하나라도 돌기 전에 컨테이너가 하나씩 건네줍니다.

덕분에 결제 제공자, 캐시 백엔드, 옆 모듈 전체를 그것을 쓰는 업무 method를 고치지 않고 교체할 수 있습니다.

plug의 단위는 adaptor입니다. adapt()로 만든 클래스이고, 주어진 이름으로 스스로 등록합니다.

service와 같은 주입기를 받되 service와 signal은 빠집니다. 그래서 adaptor는 설정, 다른 adaptor, 공유 상태를 가질 수 있지만 비즈니스 로직은 갖지 않습니다:

망고가 없어서 주문을 거절하는 것과 로그인하지 않은 고객의 주문을 거절하는 것은 같은 거절이 아니고, 같은 파일에 쓰지도 않습니다. 각 계층은 자기만 알 수 있는 것을 던집니다:

chain method가 이 규칙의 가장 작은 형태입니다. 검증하고, 값을 바꾸고, this를 돌려줍니다. 저장은 하지 않습니다. 그래야 chain이 이어 붙고, 쓰기 시점은 호출한 쪽이 정합니다:

최선을 다하는 정도의 코드는 아예 던지지 않습니다. 평범한 값을 돌려주고, 그것이 에러인지는 호출한 쪽이 정합니다:

이 스택 어디에도 Result 래퍼는 없습니다.

모든 signal은 기본 마운트되는 POST /mcp에서 MCP 서버로 AI 에이전트에게도 제공됩니다. signal 파일에 따로 적을 것도 없고, endpoint마다 켜야 하는 스위치도 없습니다.

대신 노출은 guard를 따릅니다. guard가 이미 권한 부여 결정이고, 스위치를 하나 더 두면 나중에 추가되는 endpoint가 누군가 기억해 낼 때까지 보이지 않게 될 뿐이기 때문입니다.