KPubData Product Family — 전체 시스템 아키텍처¶

KPubData Product Family(Korea Public Data Product Family)는 한국 공공데이터를 수집하고, 가공하고, 시각적으로 관리하는 세 가지 도구의 모임입니다.

각 저장소는 독립적으로 동작할 수 있지만, 함께 사용할 때 공공데이터의 전체 생명주기를 하나의 흐름으로 처리할 수 있습니다.

저장소	한 줄 역할	기술
kpubdata	공공데이터를 가져오고 표준화하는 코어 라이브러리	Python 3.10+
kpubdata-builder	수집된 데이터를 다양한 형식으로 가공하는 빌드 파이프라인	Python 3.10+
kpubdata-studio	빌드 과정을 시각적으로 관리하는 웹 대시보드	Vite + React Router + TypeScript (SPA)

0. KPubData Product Family가 뭔가요? (초보자를 위한 비유)¶

세 프로젝트의 관계를 석유공업(정유산업)에 비유하면 이해하기 쉽습니다.

원유 채굴 → 정유소 → 제어실¶

kpubdata = 원유 채굴·탈염 (Crude Extraction & Desalting)
전 세계 유전(공공기관 API)에서 원유(데이터)를 채굴합니다.
유전마다 원유의 성분(응답 형식)과 채굴 조건(인증 방식)이 제각각입니다.
탈염·탈수 공정(정규화)을 거쳐 불순물을 제거하고, 파이프라인에 넣을 수 있는 표준 원유로 만듭니다.
kpubdata-builder = 정유소 (Refinery)
표준화된 원유를 레시피(빌드 기획서)에 따라 가솔린·경유·등유 등 다양한 석유 제품(Parquet, CSV, HuggingFace Dataset)으로 분리·가공합니다.
같은 공정을 언제든 반복할 수 있도록 자동화된 플랜트를 운영합니다.
kpubdata-studio = 제어실 (Control Room)
정유소의 가동 상태를 실시간 모니터링하고, 어떤 제품을 생산할지 주문(빌드 실행)을 내리는 제어 화면입니다.
운영자가 직접 배관을 만질 필요 없이, 화면에서 클릭 몇 번으로 전체 공정을 관리합니다.

[유전 / 원유 채굴]        [정유소]              [제어실]
  kpubdata          →   kpubdata-builder  →   kpubdata-studio
  (채굴·탈염·표준화)     (석유 제품 생산)        (공정 제어·모니터링)

1. 전체 시스템 관계도¶

세 저장소와 외부 API(프로그램끼리 데이터를 주고받는 규칙), 그리고 최종 사용자 간의 관계입니다. 데이터는 아래에서 위로 흐르고, 제어(명령)는 위에서 아래로 내려갑니다.

graph TD
    U1([비개발자 / 기획자]) -->|웹 브라우저| Studio
    U2([데이터 엔지니어]) -->|CLI / Python API| Builder
    U3([파이썬 개발자]) -->|Python SDK| Core

    subgraph "KPubData Product Family"
        Studio["kpubdata-studio<br/>웹 대시보드<br/>(Vite + React Router + TypeScript (SPA))"]
        Builder["kpubdata-builder<br/>데이터 빌드 파이프라인<br/>(Python 3.10+)"]
        Core["kpubdata<br/>데이터 접속 코어<br/>(Python 3.10+)"]
    end

    Studio -->|"REST API 호출"| Builder
    Builder -->|"Python import"| Core
    Core -->|"HTTP 요청"| API1{{공공데이터포털<br/>data.go.kr}}
    Core -->|"HTTP 요청"| API2{{기상청 / 환경부<br/>기타 공공기관}}

    Builder -->|"파일 생성"| Output[(Markdown / CSV<br/>JSONL / Parquet)]

2. 전체 데이터 흐름¶

공공기관 서버에 있는 원본 데이터가 최종 사용자에게 전달되기까지의 여정입니다.

sequenceDiagram
    participant P as 공공 API<br/>(data.go.kr 등)
    participant C as kpubdata<br/>(수집/정규화)
    participant B as kpubdata-builder<br/>(조립/변환)
    participant S as kpubdata-studio<br/>(시각화/제어)
    participant U as 최종 사용자

    Note over P, C: 1단계: 원본 데이터 확보
    C->>P: HTTP 요청 (API 키 포함)
    P-->>C: Raw 응답 (XML/JSON)
    C->>C: 정규화 → RecordBatch 변환

    Note over C, B: 2단계: 데이터 가공
    B->>C: client.dataset(...).list(...)
    C-->>B: 표준화된 RecordBatch 반환
    B->>B: 필터링 + 결합 + 포맷 변환
    B->>B: Manifest(빌드 기록) 생성

    Note over B, S: 3단계: 운영 및 모니터링
    S->>B: POST /builds/run (빌드 실행 명령)
    B-->>S: 빌드 상태 + 결과물 경로 반환

    Note over S, U: 4단계: 최종 서비스
    S-->>U: 시각화된 데이터 + 다운로드 링크

단계별 상세 설명¶

원본 데이터 확보 (kpubdata)
각 공공기관의 API에 HTTP(인터넷 통신 규약) 요청을 보내 원본 데이터를 받아옵니다.
XML(태그 형식)이든 JSON(중괄호 형식)이든 자동으로 판별하여 파이썬 객체로 변환합니다.
기관마다 다른 에러 코드, 페이지 처리 방식 등을 표준 형태(RecordBatch)로 정규화합니다.
데이터 가공 (kpubdata-builder)
kpubdata를 파이썬 라이브러리로 불러와(import) 데이터를 수집합니다.
빌드 기획서(YAML — 들여쓰기로 구조를 표현하는 설정 파일)에 정의된 규칙에 따라 데이터를 변환합니다.
Markdown, CSV, JSONL, Parquet 등 원하는 형식의 파일을 생성합니다.
운영 및 모니터링 (kpubdata-studio)
웹 브라우저를 통해 빌드를 시작하거나 상태를 확인합니다.
Builder가 제공하는 REST API(웹을 통해 데이터를 주고받는 방식)를 호출하여 통신합니다.
최종 서비스 (studio → 사용자)
사용자는 웹 화면에서 빌드 결과물을 미리보기하고, 다운로드할 수 있습니다.

3. 각 저장소의 역할과 경계¶

역할 비교표¶

구분	kpubdata (코어)	kpubdata-builder (빌더)	kpubdata-studio (스튜디오)
비유	원유 수입·정제	정유소 (Refinery)	제어실 (Control Room)
핵심 역할	공공 API 연결, 인증, 데이터 정규화	데이터 변환, 파일 내보내기, 빌드 이력 관리	빌드 모니터링, 설정 UI, 결과 시각화
주요 산출물	`RecordBatch` (표준화된 데이터 객체)	파일 (Markdown, CSV 등) + `manifest.json`	웹 대시보드 화면
주요 사용자	파이썬 개발자	데이터 엔지니어, 분석가	비개발자, 기획자, 운영자

하는 일 / 하지 않는 일¶

kpubdata (코어) - 하는 일: 공공 API 연결, API 키 인증 처리, XML/JSON 응답 파싱, 데이터 정규화, 에러 표준화, 원본 데이터 접근(call_raw) - 하지 않는 일: 데이터 저장, 복잡한 변환/가공, 파일 생성, 웹 UI 제공

kpubdata-builder (빌더) - 하는 일: 빌드 기획서(BuildSpec) 검증, kpubdata를 통한 데이터 수집, 데이터 결합/필터링, 다양한 형식으로 내보내기, Manifest 생성 - 하지 않는 일: 직접적인 API 통신(kpubdata에 위임), 웹 UI 제공, 사용자 인증/인가

kpubdata-studio (스튜디오) - 하는 일: 빌드 기획서 시각적 편집, 빌드 실행/상태 모니터링, 결과물 미리보기, 게시(Publish) 관리 - 하지 않는 일: 데이터 직접 가공, 원본 API 호출, 빌드 로직 구현(Builder에 위임)

4. 의존성 방향¶

세 프로젝트의 의존성은 항상 한 방향으로만 흐릅니다. 하위 프로젝트는 상위 프로젝트가 존재하는지 알 필요가 없습니다.

graph LR
    Studio["kpubdata-studio<br/>(프론트엔드)"] -->|"의존"| Builder["kpubdata-builder<br/>(백엔드 파이프라인)"]
    Builder -->|"의존"| Core["kpubdata<br/>(코어 라이브러리)"]
    Core -->|"의존"| ExtAPI["공공 데이터 API<br/>(외부 서비스)"]

    style Studio fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style Builder fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px
    style Core fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style ExtAPI fill:#fff3e0,stroke:#ff9800,stroke-width:2px

의존성 규칙¶

규칙	설명	비유
Studio → Builder	Studio는 Builder의 API를 호출할 수 있음	제어실이 정유소에 생산 명령을 내림
Builder → kpubdata	Builder는 kpubdata를 파이썬 라이브러리로 import하여 사용	정유소는 원유 수입사로부터 원유를 공급받음
kpubdata → 공공 API	kpubdata는 외부 공공기관 서버에 HTTP 요청을 보냄	원유 수입사는 유전(공공기관)에서 원유를 채굴함
역방향 금지	kpubdata는 Builder를, Builder는 Studio를 절대 import하거나 호출하지 않음	유전이 정유소에게 "이거 만들어"라고 지시하지 않음

5. 자세한 구현 문서¶

각 프로젝트의 기술 스택, 배포 환경, 통신 방식, 로드맵 등 세부 사항은 각 저장소의 문서를 참고하세요.

프로젝트	README	ARCHITECTURE
kpubdata	README.md	ARCHITECTURE.md
kpubdata-builder	README.md	ARCHITECTURE.md
kpubdata-studio	README.md	ARCHITECTURE.md