콘텐츠로 이동

아키텍처

DataSketchers 플랫폼은 pnpm 모노레포 하나로 모든 서비스를 관리합니다. 프론트(마케팅)는 Astro 정적 사이트, 백엔드는 Go API, 그리고 MkDocs 위키와 Astro 블로그가 같은 저장소에 공존합니다.

모노레포 구조

디렉터리 역할 기술 스택
apps/site 마케팅 사이트 (data-sketchers.com) Astro 5, static, KO/EN
apps/api 백엔드 API Go + Chi + SQLite + S3
apps/wiki 이 개발 위키 Material for MkDocs
apps/blog 기술 블로그 Astro, GitLab Pages
infra/ 배포 설정 (nginx, compose) docker-compose
scripts/ 빌드/배포 보조 bash

핵심 설계 원칙

마케팅 사이트는 100% 정적입니다. 동적 로직이 필요하면 Astro에 두지 말고 apps/api의 Go 백엔드에 구현하는 것을 원칙으로 합니다.

프론트: Astro 5 + i18n

  • 정적 생성(SSG): 모든 페이지가 빌드 시 HTML로 출력됩니다.
  • i18n: prefixDefaultLocale: false 로 한국어가 기본 경로(/), 영어는 /en 접두사로 제공됩니다.
/data-sketchers.com
├── /              ← 한국어 홈
├── /en/           ← 영어 홈
└── /_astro/...    ← 정적 에셋 (롱캐시)

백엔드: Go API 스캐폴드

apps/api는 Chi 라우터 기반으로 구성되며 SQLite를 메인 스토리지로, 파일/에셋은 S3에 저장합니다.

메서드 경로 설명
GET /health 헬스체크
GET /api/events 이벤트/솔루션 목록
POST /api/events 이벤트 생성
GET /api/canvas/:id 캔버스 조회
POST /api/canvas 캔버스 저장 
apps/api/
├── cmd/api/          # 진입점
├── internal/
│   ├── handler/      # HTTP 핸들러
│   ├── service/      # 비즈니스 로직
│   ├── repo/         # SQLite/S3 접근
│   └── ai/           # LLM 어댑터 (D-SKET Canvas)
└── storage/          # SQLite 파일, 업로드

S3 용도

S3는 사용자 업로드 에셋(캔버스 이미지, 첨부파일)을 저장합니다. SQLite는 구조화된 메타데이터, S3는 바이너리 객체로 책임을 분리합니다.

배포 흐름

flowchart LR
    PUSH["git push"] --> CI["GitLab CI"]
    CI --> LINT["lint"]
    LINT --> BUILD["build-image (kaniko)"]
    BUILD --> PUSHIMG["docker push (nginx 이미지)"]
    PUSHIMG --> DEPLOY["SSH 배포 (ds-20000 호스트)"]
    DEPLOY --> UP["docker compose up"]
    UP --> TUNNEL["cloudflared 터널"]
    TUNNEL --> PUBLIC["data-sketchers.com"]

배포 상세는 CI/CD 파이프라인과 운영 & 배포에서 확인하세요.

요청 흐름

sequenceDiagram
    participant U as 브라우저
    participant CF as Cloudflare
    participant NG as nginx (컨테이너)
    participant ASTRO as 정적 파일 /_astro
    participant API as Go API (apps/api)

    U->>CF: GET https://data-sketchers.com/
    CF->>NG: 터널 경유 요청
    NG->>ASTRO: .html / 정적 에셋 서빙
    NG-->>CF: 200 HTML
    U->>CF: POST /api/events (동적)
    CF->>NG: 터널 경유 요청
    NG->>API: /api 프록시
    API-->>CF: JSON 응답

현재 상태: /api 프록시

nginx의 /api 프록시 설정은 TODO 상태입니다(미구현). 지금은 정적 마케팅 + 간헐적 방식으로 서빙합니다. /api 사용 전 반드시 운영 & 배포를 확인하세요.