All File Converter 서비스는 현대적인 Python 3.12 비동기 스택을 기반으로 하는 확장 가능한 분산형 SaaS 시스템으로 설계되었습니다. 아키텍처는 네트워크 이벤트 수신, 작업 오케스트레이션, 무거운 바이너리 프로세스의 격리된 실행, 그리고 분석 루프의 독립된 계층으로 분리되어 있습니다.

1. 전체 기술 스택 및 시스템 아키텍처

플랫폼의 기반에는 고통신량(high-throughput), 최소한의 메모리 소비, 그리고 장애 방지 원칙이 내장되어 있습니다.

  • Telegram Bot Framework: 보안 토큰 검증 및 커스텀 메시지 수명 주기 필터를 갖춘 Webhook 모드로 작동하는 Aiogram 3.13.
  • 웹 게이트웨이 및 REST API: 바이너리 파일의 비동기 스트리밍 전송(FileResponse)과 BackgroundTasks를 통한 백그라운드 정리를 지원하는 Uvicorn ASGI 서버 기반의 FastAPI.
  • 대기열 브로커 및 캐시: Redis 7 (Celery 작업 관리, 경쟁 상태 방지 락, 무차별 대입 공격 방지, 세션 캐싱).
  • 백그라운드 실행기 (Task Queue): 격리된 converter_worker 컨테이너 내 전용 워커 풀이 있는 Celery 5.4.
  • 데이터베이스: PostgreSQL 16, ORM 계층 SQLAlchemy 2.0 (asyncpg), 영구 연결 풀(20+10 overflow), 그리고 실패한 트랜잭션 자동 재시도(@db_retry) 지원.
  • 네트워크 루프: 미들웨어를 통해 서버에 대한 직접 IP 접근을 차단하는 Cloudflare Zero Trust를 통한 터널링.

2. 비동기 대기열 및 고부하 연산 격리 (Celery + Redis)

미디어 파일 및 오피스 문서 변환은 CPU와 RAM에 최고 부하를 발생시킵니다. 무거운 작업 수행 시 Telegram의 수신 메시지 처리 과정이 차단되지 않도록 엄격한 격리가 구현되어 있습니다.

  • Redis로 작업 위임: 포맷 선택 시 Telegram 핸들러는 DB에 상태를 PROCESSING으로 하여 작업을 등록하고, Celery를 통해 tasks.execute_conversion 대기열에 작업을 넣습니다.
  • 격리된 워커 컨테이너: 변환 유틸리티의 실행은 자체 프로세서 시간 및 메모리 제한이 있는 별도의 Linux 컨테이너 내에서 이루어집니다.
  • 중단 제어 및 시간 초과: 외부 유틸리티 호출은 엄격한 시간 제어(conversion_timeout_sec = 180)와 함께 비동기 컨텍스트로 감싸져 있습니다. 제한 시간 초과 시 프로세스는 proc.kill()을 통해 강제 종료되어 리소스를 해제합니다.
  • 내장애성 Fallback: Redis 브로커가 일시적으로 사용 불가능할 경우, 작업은 로컬 비동기 디스패처에 의해 자동으로 가로채어져 사용자 중단 없이 직접 실행됩니다.

3. 특화된 변환 엔진 파이프라인

각 데이터 유형별로 특화된 네이티브 유틸리티와 라이브러리가 사용됩니다.

  • 문서 및 표 (LibreOffice): DOCX, XLSX, PPTX, RTF, ODT를 PDF 또는 텍스트 파일로 정확하게 렌더링하기 위한 헤드리스 오피스 패키지(soffice --headless).
  • 스트리밍 오디오 및 비디오 (FFmpeg): 비디오 코덱(H.264), 오디오 코덱(MP3, OGG Opus) 멀티스레드 재인코딩, 오디오 트랙 추출, GIF 생성(Lanczos 필터), 그리고 Telegram 비디오 메시지 정사각형 자르기(1:1).
  • 고속 PDF 처리 (Poppler Utils): pdftotext (포맷팅된 텍스트를 UTF-8로 즉시 추출) 및 pdftoppm (LibreOffice 오버헤드 없이 PDF를 래스터 이미지로 페이지별 렌더링) 유틸리티.
  • 광학 문자 인식 (Tesseract OCR): 40개 이상의 언어로 스캔본 및 사진에서 인쇄된 텍스트를 신경망으로 추출.
  • 래스터 및 벡터 그래픽: Pillow 라이브러리 (HEIC 및 AVIF 포맷 지원 포함), 벡터 이미지를 위한 CairoSVG, Telegram 애니메이션 스티커(.TGS)를 위한 lottie.
  • 도서, 자막 및 폰트: Calibre 엔진 (ebook-convert), 자막 파서 pysubs2 (SRT, VTT, ASS, SSA), 폰트 컴파일러 fonttools (WOFF2 브로틀리 압축).

4. 예방적 자원 보호 (System Guard)

메모리 부족(OOM Killer)으로 인한 서버 다운을 방지하기 위해 예방적 진단 서비스인 System Guard가 도입되었습니다. 처리를 위해 파일을 수락하기 전에 시스템은 호스트의 핵심 지표를 확인합니다.

  • 가용 RAM: 최소 500MB의 여유 용량 (guard_min_free_ram_mb).
  • 디스크 공간: /tmp 디렉터리에 최소 2GB의 여유 공간 (guard_min_free_disk_mb).
  • 작업 대기열: Celery 대기열 길이 제한 (대기 중인 작업 20개 이하).

한계를 초과할 경우 서비스는 보호 기능을 일시적으로 활성화(HTTP 503 / 채팅 메시지 전송)하여 서버 과부하를 방지하고 Telegram의 관리자에게 즉시 경고를 보냅니다.

5. 파일 수명 주기 및 보안 (GDPR)

아키텍처는 Zero-Data-Footprint 모델로 설계되었습니다.

  • 사용자 파일은 작업 ID를 기반으로 하는 고유한 접두사와 함께 보안 볼륨 tmp/conversions/에 업로드됩니다.
  • 파일은 엄격하게 작업 세션 내에서만, 즉 15분 이하(900초) 동안만 액세스할 수 있습니다.
  • 자동 가비지 컬렉터는 채팅으로 성공적으로 전송되었다는 확인을 받은 직후 또는 세션 타임아웃 만료 시 원본 및 완성된 파일을 즉시 지웁니다.
  • PostgreSQL 데이터베이스는 바이너리 파일이나 문서의 개인 텍스트를 저장하지 않으며, 테이블에는 익명화된 기술 메타데이터(포맷, 바이트 단위 크기, 작업 시간, 상태)만 기록됩니다.

6. 외부 웹 서비스를 위한 범용 REST API

이 서비스는 애초부터 멀티플랫폼 백엔드로 설계되었습니다. 봇과 함께 웹사이트(예: Django 기반) 및 서드파티 봇을 위한 완전한 보안 프로그래밍 인터페이스가 작동합니다.

  • GET /api/v1/formats — Google 스프레드시트 설정과 동기화된 사용 가능한 변환 방향의 동적 JSON 매트릭스.
  • POST /api/v1/convert — multipart/form-data(파일, 대상 포맷, 외부 클라이언트 ID)를 수락하고 직접 다운로드 형태로 바이트 스트림을 반환하는 범용 엔드포인트.
  • secrets.compare_digest를 통한 타이밍 공격 방지가 포함된 Bearer 토큰(WEBHOOK_REFRESH_TOKEN) 인증.

7. 제어판 및 Observability (NiceGUI + AG Grid)

비즈니스 지표 및 시스템 상태 모니터링은 NiceGUI 2.x 기반의 네이티브 Single-Page 제어판으로 출력됩니다.

  • 커스텀 Excel 스타일 체크박스 필터(aggrid_filters.js)가 포함된 대화형 AG Grid (v32+) 테이블.
  • 대기열, API 제공자 지연 시간, PostgreSQL / Redis 핑 실시간 모니터링.
  • 서명된 JWT 토큰을 통한 Metabase BI 대시보드의 심리스한 통합과 날짜별 엔드투엔드 필터링.