Loafacto Hub 문서

Appearance

Loafacto 문서/참고 문서/backend-server 문서/Backend Server Architecture

Backend Server 아키텍처 ​

백엔드 서버는 API 레이어를 중심으로 인증, 도메인 로직, AI 실행, 검색/임베딩, 저장소 연동이 분리된 구조로 운영합니다.

계층 구성 ​

  • presentation 계층
    • HTTP 요청/응답 처리
    • 라우트 정의, 입력 검증, 에러 핸들러
  • application 계층
    • 유스케이스/서비스 조합
    • 트랜잭션 경계 관리
  • domain 계층
    • 사용자, 프로젝트, 문서, 작업, 에이전트 정책을 담당하는 핵심 로직
  • integration 계층
    • Supabase, 외부 AI API, 오브젝트 저장소 등 외부 의존성 호출
  • infra 계층
    • 로그, 메트릭, 캐시, 큐, 마이그레이션, 배포 환경 설정

런타임 시퀀스 ​

mermaid
sequenceDiagram
  participant U as User
  participant FE as Web UI
  participant API as Backend API
  participant A as Agent Engine
  participant R as RAG Pipeline
  participant S as Supabase / DB

  U->>FE: 기능 요청
  FE->>API: REST/WS 호출
  API->>API: 인증/권한/검증
  alt Agent 요청
    API->>A: 실행 Task 전달
    A->>S: 컨텍스트 조회
    A->>R: 검색 호출
  else 문서/검색 요청
    API->>R: 인덱스/검색 요청
  end
  R->>S: 벡터/메타 조회
  API-->>FE: 정규화된 응답

핵심 저장소/도메인 데이터 ​

  • 메타데이터 DB
    • 사용자, 프로젝트, 문서 상태, 작업 히스토리
  • 벡터 DB / 확장 스토리지
    • 청크 단위 임베딩, 거리 기반 검색 인덱스
  • 오브젝트 스토리지
    • 원본 문서, 이미지, 로그 아카이브

운영 포인트 ​

  • 에이전트 실행은 동시성 제한이 중요하므로 큐 또는 작업 제한을 둡니다.
  • RAG 파이프라인은 비동기 처리 후 상태를 추적하여 실패 재시도와 오류 알림을 제공합니다.
  • 검색 품질은 chunk 크기, 임베딩 모델, 리랭크 전략에 따라 크게 달라집니다.