구현, 아키텍처

개요

이 글을 읽기 전에,
이 프로젝트는 두 가지 아키텍처를 전제로 설계·구현되었다는 점을 먼저 설명하고 싶다.

• 개발용 아키텍처
• 실 서비스(운영) 아키텍처

두 환경은 목적이 다르기 때문에
구성도 명확히 분리되어 있다.

실 서비스용 아키텍

개발용 아키텍처

---

아키텍처 개요

개발용 아키텍처

개발 단계에서는 EC2 서버 중심 구조를 사용했다.

• EC2 서버에
  • Backend
  • Frontend
  • Database
• 임베디드 보드는
  • 네트워크를 통해 서버와 HTTP 통신

개발, 테스트, 디버깅을 빠르게 반복하기 위한 구조다.

---

실 서비스 아키텍처

실 서비스 환경에서는
냉장고 내부 장비 중심 구조로 전환된다.

• 냉장고 내부 Raspberry Pi
  • Frontend
  • Backend
  • Database
  • 임베디드 제어
• Jetson Orin
  • 카메라 인식
  • 챗봇 기능

외부 서버 의존도를 최소화하고,
현장에서 독립적으로 동작하도록 구성했다.

---

구성 요소

서버 / 인프라

• FastAPI (Backend)
• PostgreSQL (이력 / 재고)
• Redis (실시간 상태 / 캐시)
• Docker / Docker Compose
• Jenkins (CI/CD)
• Nginx Proxy Manager (Reverse Proxy)

임베디드

• Raspberry Pi / Jetson
• 카메라, 센서 입력
• 서버 API 호출 전용 클라이언트

---

네트워크 및 접근 방식

• 하나의 host 아래에서
  /서비스명 형태의 경로 기반 라우팅 사용
• Backend는 root_path를 명시적으로 설정
• 경로 기반 라우팅이 맞지 않는 서비스(Supabase 등)는
  별도 도메인으로 분리
• 개발 PC / 서버 / 보드는
  Tailscale로 동일한 사설 네트워크처럼 연결

---

Backend 동작 방식

• Draft 데이터는 브라우저에서만 관리
• 서버에는 Commit 시점에만 요청
• DB에는 확정 데이터만 저장
• 모든 주요 데이터는 세션 ID 기준으로 묶음

---

데이터 모델 핵심

• 마스터 / 이력 / 현재 상태 분리
• 입고 1건 = 인스턴스 1개
• 재고(inventory)는 현재 상태 스냅샷
• 이력(inbound / outbound)은 단일 진실의 원천

---

임베디드 역할

• 데이터 수집
• 이벤트 생성
• 서버 전달

임베디드 보드는 상태를 저장하지 않고,
항상 서버를 기준으로 동작한다.

---

요약

• 서버는 기록과 판단
• 보드는 입력과 이벤트
• 인프라는 연결과 배포

이 구조를 기준으로
개발, 테스트, 실 서비스 운영을 진행했다.