Sticker Automation Project - Architecture & Structure

본 프로젝트는 etsy에서 custom name sticker를 판매하는 회사의 의뢰입니다.
지금까지 주문이 들어오면 손님의 이름을 포토샵에서 일일이 타이핑해서 인쇄하였습니다.
하지만 이방식으로 하면 시간도 많이 투입되고 오타 입력의 가능성도 많았습니다.

🏗️ 1. 전체 아키텍처 개요 (Overview)

이 프로젝트는 Next.js 14 (App Router 기반)와 Prisma ORM (MySQL) 을 사용하여 풀스택으로 구축되었습니다. Etsy API와 연동하여 주문을 자동으로 수집하고, 수집된 데이터를 바탕으로 스티커 인쇄용 고해상도 PDF 및 PNG 이미지를 자동 생성(Sharp, PDFKit 활용)하는 자동화 시스템입니다. 모든 시스템은 Docker 컨테이너 환경에서 안정적으로 동작하도록 설계되었습니다.

📂 2. 폴더 및 파일별 기능 설명 (Directory Structure)

📁 src/app (프론트엔드 UI & 백엔드 API 라우트)

Next.js의 App Router 구조를 따르며, 사용자가 보는 웹 화면과 서버 API가 모두 포함되어 있습니다.

• / (page.tsx)

  • 메인 대시보드 화면입니다.

  • Etsy 주문 목록을 테이블 형태로 조회하고, 수정, 폰트/디자인 변경, 주문 분할(Split) 및 복구 기능을 제공합니다.

• /settings (page.tsx)

  • 시스템 설정 화면입니다. Etsy API 연동 버튼과 현재 연동 상태를 확인합니다.

• /api (백엔드 API 서버)

  • /api/etsy/auth & /callback: Etsy API OAuth 2.0 인증 및 토큰 발급/갱신을 담당합니다.

  • /api/etsy/orders: Etsy API에서 실시간(결제 완료건) 주문 데이터를 긁어와서 데이터베이스에 저장(Sync)합니다. 이때 대소문자 변환 로직 등이 적용됩니다.

  • /api/orders/pending & printed: 대기 중인 주문과 인쇄 완료된 주문 데이터를 데이터베이스에서 불러옵니다. (order_time 최신순 정렬)

  • /api/orders/[id]/split & unsplit: 주문을 원하는 수량과 디자인으로 나누거나(Split) 다시 합치는(Unsplit) 기능을 처리합니다.

  • /api/generate/pdf & /image: 선택한 주문들을 바탕으로 실제 스티커 인쇄용 A4/Letter 사이즈 PDF 파일이나 개별 PNG 이미지를 생성합니다.

📁 src/lib (핵심 비즈니스 로직 및 유틸리티)

앱 전반에서 재사용되는 핵심 기능 모듈들이 모여 있습니다.

• /etsy (client.ts)

  • Etsy API 통신을 전담하는 클라이언트입니다. 토큰 만료 시 자동으로 Refresh 하는 로직과 영수증(Receipt) 정보를 호출하는 기능이 포함되어 있습니다.

• /sharp (image-engine.ts)

  • [가장 중요한 핵심 모듈] Sharp 라이브러리와 SVG 렌더링을 이용하여 폰트를 렌더링하고, 배경 이미지와 합성하여 고해상도(300 DPI) 스티커 이미지를 그려냅니다. (이름 길이에 따른 유연한 스케일링, font7의 1.2배 확대 로직 등이 이곳에 있습니다.)

• /pdf (pdf-generator.ts)

  • 생성된 스티커 이미지들을 인쇄용 PDF 종이(A4 등) 규격에 맞게 격자(Grid) 형태로 정렬하고 여백을 계산하여 하나의 PDF 문서로 병합합니다.

• /config (templates.ts)

  • 각 스티커 제품별(원형, 사각형, 크기별) 격자 크기, 여백(mm), 폰트 최대 크기 한계치 등을 정의한 설정 파일입니다.

• prisma.ts

  • 데이터베이스 통신을 위한 Prisma Client 싱글톤 객체입니다.

📁 prisma (데이터베이스 구조)

• schema.prisma

  • 데이터베이스 테이블 구조(모델)를 정의합니다.

  • Order(주문 정보), EtsyToken(토큰 정보), TargetListing(수집 대상 상품 설정) 등의 테이블 구조가 명시되어 있습니다.

📁 public (정적 파일 및 에셋)

• /assets

  • 폰트 파일(.otf, .ttf)과 배경 디자인 이미지(.png)들이 저장되는 공간입니다.

  • Docker 실행 시 외부 폴더와 볼륨(Volume)으로 연결되어, 폴더에 파일을 추가하기만 하면 서버 재시작 없이도 즉시 반영됩니다.

📁 프로젝트 루트 (설정 파일들)

• docker-compose.yml & Dockerfile

  • 프로젝트를 도커 컨테이너로 빌드하고 실행하기 위한 설계도입니다. MySQL DB 컨테이너와 Web 컨테이너를 함께 띄웁니다.

• next.config.js

  • Next.js 빌드 설정입니다. 도커 환경에 맞게 standalone 모드로 압축 빌드되도록 설정되어 있습니다.

• package.json

  • 설치된 외부 라이브러리(Sharp, PDFKit, Prisma 등) 목록이 기록되어 있습니다.

🚀 3. 최종 시스템 요약

고객님은 이제 Etsy에 주문이 들어오면 웹 화면에서 [Sync] 버튼 한 번으로 주문을 불러오고, 원하는 디자인과 폰트를 맞춤 설정한 뒤 [Print] 버튼을 눌러 인쇄소에 바로 넘길 수 있는 고품질 PDF를 생성하는 완벽한 자동화 파이프라인을 소유하게 되셨습니다.