Stateless AI 애플리케이션의 아키텍처
Source: Dev.to
프로젝트는 위험해 보이는 결정으로 시작되었습니다: 백엔드 데이터베이스 없음.
당시에는 사용자 데이터를 영구 저장할 필요가 없었으며—사용자의 응답을 받는 것이 최우선이었습니다. 대부분의 튜토리얼은 계정, 세션, 데이터를 PostgreSQL, MongoDB, DynamoDB 등에 저장한다고 가정하지만, 이 앱은 기기 간에 어떤 것도 영구 저장할 필요가 없습니다.
3계층 분리
- 프론트엔드 – 모든 사용자 인터랙션, UI 상태, 이미지 압축, 다단계 마법사 흐름, 로컬 히스토리, 결과 렌더링을 담당합니다.
- 백엔드 – 하나의 책임만 수행: 이미지 데이터를 진단 데이터로 변환합니다. 요청을 받고, 프롬프트를 구성하고, LLM을 호출하고, 응답을 파싱해 구조화된 JSON을 반환합니다. 상태, 세션, 데이터베이스가 없습니다.
- AI 레이어 – Claude Vision이 제작된 프롬프트와 함께 이미지를 받아 상세 진단 정보를 반환합니다.
각 레이어는 정확히 한 가지 일만 합니다. 책임을 혼합하면(예: 백엔드에서 히스토리를 저장하거나 프론트엔드에서 직접 LLM을 호출) 불필요한 복잡성이 추가됩니다.
데이터 상호작용
- 히스토리와 설정은 절대 사용자의 기기를 떠나지 않습니다.
- API 키는 서버를 통과하지만 절대 저장되지 않습니다.
다단계 마법사: 왜 상태 머신인가
스캔 흐름에는 최대 다섯 단계가 포함될 수 있습니다:
- 식물 부위 선택
- 작물 종류 선택
- 미디어 업로드
- 분석 모드(단일 이미지 vs. 다중 이미지)
- 컨텍스트 입력
전통적인 번호 매김 단계는 모드 4의 존재 여부가 런타임 조건(단일 vs. 다중 이미지)에 따라 달라지기 때문에 모호해집니다.
해결책: 의미 있는 상태 이름(part, crop, media, mode, context, analyzing)을 가진 상태 머신을 사용합니다. UI는 현재 상태에 따라 렌더링되고, 진행 표시기는 동적으로 계산되어 하드코딩된 단계 번호 없이도 사용자 경험을 정확하게 유지합니다.
저장소 아키텍처: 3계층
| 계층 | 목적 | 일반적인 내용 |
|---|---|---|
| 세션 스토리지 | 브라우저가 닫히면 만료되는 동의 플래그를 보관합니다. | 건강 관련 데이터에 대한 동의 선택 |
| 로컬 스토리지 | 세션 간 데이터를 영구 보관합니다. | 스캔 히스토리, 접근성 설정(글꼴 크기, 음성 선호도), API 키 |
| 내장 딥 캐시 | 각 히스토리 항목에 대한 전체 진단을 저장합니다(25개 이상의 필드). | 치료법, 예방 팁, 전체 결과 페이로드 |
딥 캐시는 저장 용량을 늘리지만 실제 오프라인 접근을 가능하게 합니다—농촌 사용자에게는 필수적입니다. 일반적인 스캔은 20–30 KB이며, 최대 약 50개의 스캔을 저장해도 총 용량은 ~1.5 MB에 불과해 5 MB 브라우저 할당량을 충분히 넘지 않습니다. 오래된 스캔은 자동으로 순환됩니다.
단일 엔드포인트 철학
백엔드는 오직 하나의 API 엔드포인트만 제공합니다:
POST /api/v1/analyze
모든 분석 모드(단일 이미지, 배치, 비디오)는 mode 파라미터로 처리되며, 이 파라미터가 프롬프트 구성과 응답 처리를 조정합니다. 이렇게 하면 다음을 피할 수 있습니다:
- 중복된 검증 로직
- 복잡한 클라이언트‑사이드 라우팅
- 여러 엔드포인트에 대한 버전 관리 문제
- 추가 문서 작업 부담
잘 문서화된 단일 엔드포인트는 테스트와 유지보수가 훨씬 간단합니다.
사용자 제공 API 키
- 비용 투명성: 사용자는 자신이 지불하는 금액을 정확히 확인할 수 있어 숨겨진 마크업이 없습니다.
- 키 관리 불필요: 키를 저장하거나 교체할 데이터베이스가 필요 없어 운영 복잡성이 감소합니다.
- 확장성: 각 사용자는 자체 Anthropic 할당량을 가지므로 공유 레이트 제한이 없습니다.
- 신뢰: 사용자는 자신의 자격 증명을 직접 관리하므로 개발자가 예기치 않은 비용을 발생시킬 수 없습니다.
단점은 마찰입니다—사용자는 앱을 사용하기 전에 Anthropic 계정을 만들고 API 키를 생성해야 합니다. 이는 기술적인 대상에게는 괜찮지만, 대중 시장을 겨냥할 경우 재고가 필요합니다.
배치 모드 vs. 단일 모드: 같은 식물 문제
여러 이미지를 업로드하면 시스템은 이 이미지들이 다른 식물을 나타내는지(별도 분석) 혹은 다른 각도에서 촬영한 같은 식물인지(함께 분석) 판단해야 합니다.
(이 결정 로직의 구현에 대한 자세한 내용은 원문 기사에서 계속됩니다.)