데이터엔지니어링 프로젝트 구조 표준 골격(README·환경설정·컨테이너·src 5계층·CI/CD)에 이 프로젝트의 실물 구성환경(AWS 에뮬레이터 + 로컬 하이브리드) 을 그대로 사상한 구성 문서
판정 기준
구성 요소가 실측으로 존재하고 동작하는가(R3). 상태 3값: [실재] 로컬 하이브리드 환경에 존재·실측 통과 / [부분] 일부만 존재하거나 수동 절차로 대체 중 / [제안] 실환경 전환(D-1) 시 새로 작성
실물 위치
스크립트·규칙·검증기는 aws-emulator/local/·aws-emulator/scripts/, 근거 문서는 05·06·07·10·12호
주의
이 문서의 트리는 목표 레포 골격(실환경 전환 시의 코드 배치)이며, 각 노드에 현재 실물 경로와 상태를 병기했다 — 아직 그 경로로 코드를 옮겼다는 뜻이 아니다
1 전체 구조 트리 (표준 골격 ← 실물 사상)
건설도면프로젝트/ ← 데이터엔지니어링 표준 골격
├── README.md [실재] aws-emulator/08_README.md
├── .env.example [부분] scripts/env-wsl.sh · env-windows.ps1 + 파이프라인 매개변수
├── .gitignore [제안] 모델 체크포인트·인증서·데이터 제외 규정 필요
├── docker-compose.yml [부분] 컨테이너 4종이 개별 docker start 로 기동 중
├── Dockerfile [부분] osb-runner 컨테이너 수동 구성 (python 3.12-slim)
├── pyproject.toml [제안] 현 검증 스크립트는 파이썬 표준라이브러리만 사용
├── src/
│ ├── ingestion/ [실재] OCR·합성 도면·S3 원본 적재·이벤트 소비
│ │ ├── ocr_extractor ← api_extractor.py 자리 (test-ocr*.sh, Tesseract 5.5)
│ │ ├── synthetic_builder ← 합성 도면 생성+기하 검출 (t23-pipes.py, 16/16)
│ │ └── event_consumer ← kafka_consumer.py 자리 (SQS/EventBridge, t27-consumer.py)
│ ├── dags/ [실재] 종단 파이프라인·manifest 배치
│ │ ├── pipeline_end2end ← daily_sales_dag.py 자리 (test-pipeline.sh, 전 단계 통과)
│ │ └── manifest_batch ← backfill_dag.py 자리 (t27-batch.py, 재실행 멱등 7/7)
│ ├── transform/
│ │ └── models/ [실재] 인덱스 매핑·임베딩 적재·질의 템플릿 계약
│ │ ├── index_mapping ← stg_orders.sql 자리 (k-NN lucene·하이브리드 파이프라인)
│ │ └── query_templates ← fct_sales.sql 자리 (t26-templates.json, 12/12)
│ ├── tests/ [실재] 관계 제약 검사기·품질 규칙
│ │ ├── t24_check ← test_transforms.py 자리 (t24-check.py, E101~E111·H201)
│ │ └── data_quality ← data_quality.yml 자리 (t24-rules-v2.json + baseline)
│ └── infra/ [실재] 인덱스·역할·RLS·기동 절차를 코드로
│ ├── setup_opensearch ← main.tf 자리 (setup-opensearch.sh)
│ └── pg_roles_rls ← variables.tf 자리 (test-pg-rls.sh, 전 항목 통과)
└── .github/workflows/ [제안]
├── ci.yml ← 모든 변경에 전 검증 재실행 (현재 수동)
└── deploy.yml ← gold 게시 = 별칭 원자 전환 + 원장 기록
상태 집계: [실재] 5계층 전부(ingestion·dags·transform·tests·infra) — 다만 파일이 표준 골격처럼 한 레포에 모여 있지 않고 aws-emulator/local/에 흩어져 있다. 루트 6파일 중 [실재] 1·[부분] 3·[제안] 2.
사상 방향: 이미지 표준의 Airflow·Kafka·dbt·Terraform 자리에 이 프로젝트의 대응물(스크립트 오케스트레이션·SQS/EventBridge·인덱스 매핑 JSON·셋업 스크립트)을 놓았다. 실환경 전환(12호) 시 Airflow·Terraform 등 관리형으로 승격하는 경로는 12호 D-1 설계가 원천이다.
2 루트 파일 — 구성 카드
2.1 README.md [실재]
표준 역할: 프로젝트 개요와 아키텍처 다이어그램 / 설정·실행·배포 절차 / 데이터 원천·소유자·SLA.
파이프라인 매개변수(스크립트 인자·env로 실측): EMB_MODEL/EMB_DIM(기본 nomic-embed-text/768 → bge-m3/1024 전환 실증), KEV_MIN_CONF=0.5(게이트 임계), GW_MAIN_DISABLE_THINKING=1(메인 LLM). 통합 .env.example 파일로 뽑아둔 것은 없다 — [부분].
2.3 .gitignore [제안]
표준 역할: 저장소에 들어가면 안 되는 생성물·비밀·대용량 자산 제외.
이 프로젝트에서 제외해야 할 실물: 모델 체크포인트(/models/Ornith-1.5-9B-FP8 등 수 GB), 에뮬레이터 인증서·자격증명(~/.aws/emulator/9297/ca.pem — 기동마다 재생성되므로 커밋 무의미), 인덱스 데이터(/opt/seachdog/data/* — 크래시 후 초기화 대상), __pycache__/, 합성 도면·OCR 결과물.
아직 파일로 존재하지 않는다 — [제안].
2.4 docker-compose.yml [부분]
표준 역할: 명령 한 줄로 전체 스택 로컬 기동 / 주요 서비스를 컨테이너로 / 모든 팀원이 동일 환경.
실물(컨테이너 4종, 현재 개별 docker start):
컨테이너
포트
용도
ornith-vllm
8001
메인 LLM(vLLM, Ornith-1.5-9B-FP8, 262K ctx, dflash 스펙추론)
llm-gateway
8092
T14 선별 메인 경로(OpenAI 호환, secu-mainllm → ornith-vllm 업스트림)
운영 함정(실측): WSL 종료 시 vLLM 컨테이너가 내려간다(재시작 정책 no) → docker start ornith-vllm 후 로드 ~90초. 일괄 기동 compose 파일은 없다 — [부분].
2.5 Dockerfile [부분]
표준 역할: 로컬 실행 환경을 이미지로 고정.
실물: osb-runner(python:3.12-slim + opensearch-benchmark 2.5.0)만 컨테이너 격리 — WSL 기본 python 3.14가 OSB 요구(<3.14)에 맞지 않아서다. Dockerfile 파일은 없고 수동 구성 — [부분].
나머지 구성요소는 호스트(WSL) 직접 설치를 택했다: OpenSearch는 전체 플러그인 배포(k-NN/neural/flow-framework), PG 18은 apt, Tesseract는 eng/kor 언어 팩.
2.6 pyproject.toml [제안]
표준 역할: 파이썬 패키지·도구 의존 선언.
실물 상태: 검증 스크립트(t24-check.py·t25-paths.py·t26-run.py·t27-*.py)는 표준라이브러리만 사용해 의존 선언이 없어도 재현된다 — 이것이 오히려 이식성 근거. 유일한 외부 의존은 평가 스위트(repos/aws-emulator-evaluation-suite)의 uv sync --locked --extra checks.
의존 고정 파일은 없다 — [제안] (전환 시 boto3·requests 등 실사용 목록을 그때 고정).
3 src/ingestion/ — 수집·원본 적재 [실재]
표준 역할: API·파일·스트림에서 수집 / 가공 없이 bronze 레이어에 원본 적재 / 멱등 적재·재시도 안전.
실물 3계통:
실물
표준 자리
내용·실측
test-ocr*.sh (Tesseract 5.5)
api_extractor.py
도면 OCR 추출·품질 기록(T21/S01). PUMP 정확 인식(conf 84·bbox 정확), P101→"Pil" 오인식은 오류 사례로 보존. 비전 OCR(Ornith)도 합성 비트맵은 오인식(P101→'P4H1') — 엔진 공통 스트레스 사례
t23-pipes.py
(합성 생성기)
합성 도면 5사례(접점/교차/끊김/타페이지/모호) 생성+기하 검출 — 도트 폭 임계로 교차≠연결 구분. 16/16 통과, 기하 파라미터는 결과 JSON geometry_rules에 항상 기록
t27-consumer.py
kafka_consumer.py
SQS/EventBridge 이벤트 소비 — 변경·삭제 이벤트 적용, 멱등(DUPLICATE)·역순(STALE) 판정, 새 판 reindex+별칭 원자 전환. 18/18 통과, 원장 seachdog_event_ledger·상태 seachdog_entity_state에 이력 영구 기록
bronze 적재: S3 원본 보관(T07, 에뮬레이터 9297) — as-is 원칙. 에뮬레이터 리소스는 메모리 상주라 중지 시 소멸(테스트마다 재생성이 설계 일부).
함정 기록(수집 계층): 흰목록(tessedit_char_whitelist) 지정 시 conf가 4~90으로 요동 → 신뢰도 필터 폐기, 패턴+정규화(O→0)로 방어. PaddleOCR는 ARM64 휠 부재로 불가(소스 빌드/x86 에뮬레이션 외 없음 — 기록 확정).
4 src/dags/ — 오케스트레이션 [실재]
표준 역할: 파이프라인 정의 / 일정·재시도·태스크 의존성 / 수집·품질검사 트리거.
실물: Airflow 대신 셸 순서 + manifest 배치로 동일 통제를 실측:
실물
표준 자리
내용·실측
test-pipeline.sh
daily_sales_dag.py
종단 통합: S3→OCR→적재→BM25→메인 LLM 선별(3초, 정확)→kev grounding(supported, conf 0.829)→v2 게시→SQS→재조회. 전 단계 통과. 메인 LLM 다운 시 mica 폴백, kev 다운 시 grounding 생략(기록) — 실패도 경로로 설계
t27-batch.py
backfill_dag.py
manifest 배치: 엔트리별 소비자 호출(표준입력), 부분 실패 지속·재실행 멱등. 7/7 통과 — 1차 applied=1/blocked=1/failed=1, 2차 duplicate=2, manifest 요약 원장 기록
test-failure-paths.sh
(재시도·보류 규칙)
LLM 결함 4종→전부 needs_review(보류), grounding 임계 단위, BLOCKED 종단, 승인 직전 후보 해시 대사 시 재검사(자동 이월 금지). 9/9 통과
일정 트리거는 아직 수동(스크립트 실행) — cron/Airflow DAG화는 [제안](12호 D-1). 의존성·재시도·멱등성 통제 자체는 이미 실측으로 확보돼 있다.
태스크 코드 체계: T21(OCR)·T23(물리연결)·T24(제약검사)·T25(경로탐색)·T26(매개변수 질의)·T27(변경게시) — 01호 실행계획이 원천.
5 src/transform/models/ — 변환·계층 모델 [실재]
표준 역할: 레이어별 모델 / staging→intermediate→marts 계층화 / 테스트·문서·계보 내장.
계층 대응:
표준 계층
건설도면 실물
보관소
bronze(staging)
원본 도면 as-is(T07)
S3(에뮬레이터 9297)
silver(intermediate)
청크+벡터 색인·관계 판
로컬 OpenSearch 9200 — 문서 인덱스·seachdog_relations_pub(관측 관계만 게시, 파생=DERIV-*+전제·규칙 버전)
gold(marts)
게시 판(current)
별칭 원자 전환 — reindex 후 스위치, 게시 이력은 원장에 영구 기록
실물 구성 요소:
인덱스 매핑: k-NN method.engine은 반드시 lucene — ARM64 nmslib은 세그먼트 병합 중 JVM 크래시(공식 빌드 결함 실측). 차원 768(nomic)·1024(bge-m3) — 한국어 비교 bge-m3 5/5 vs nomic 3/5로 전환 권장(임베딩 212ms 실측).
하이브리드 파이프라인: 2.13 키는 phase_results_processors(복수형) — 단수형은 "지원하지 않는 파라미터" 오류. 점수 정규화 min_max+산술평균 실측. 단, 이 코퍼스에선 kNN 단독(bge-m3) 5/5 > 하이브리드 4/5 — 결합이 손해인 사례까지 기록했고 가중치는 평가셋 스윕으로 정한다(T13).
질의 템플릿 계약: t26-templates.json — 템플릿 사전·값 검증·psql stdin 전달. SQL을 코드에 문자열로 두지 않는 것이 계약의 핵심.
계보: 원장(seachdog_event_ledger)에 event_id·run_id·상태(applied/duplicate/stale/blocked/failed)를 영구 기록 — 표준 dbt lineage의 대응물.
6 src/tests/ — 검증·데이터 품질 [실재]
표준 역할: 변환 로직 단위 테스트 / 데이터 검사(null·중복·범위) / 모든 PR에서 자동 실행.
실물: 품질 규칙을 코드가 아니라 데이터(JSON) 로 관리하는 것이 설계 특징:
실물
표준 자리
내용·실측
t24-check.py + t24-rules-v2.json
data_quality.yml
T24 관계 제약 검사기(코드·JSON 필수 최소) — v1 13사례 13/13: 참조 존재(E103)·유효기간(E109)·supersedes 순서(E110)·방향(E105) 구분 검출. v2 좌표 계약(E111: location={coord_system,page,bbox}) 4/4
t24-baseline.json
(기준판)
기대 결과 기준판 — 규칙 변경 시 새 버전 파일 + 기준판 갱신, 결과물은 규칙·기준판 버전과 후보 해시를 남긴다
test-grounding.sh
(사실성 검사)
kev-9b 3-way(지지 0.949/모순 0.966/근거불충분 0.988) — 3사례 전부 정확, ~1초/건. 주의: 검증기 입력에 게이트 이력("T24 통과")을 넣으면 supported로 편향(실측)
test-relation.sh
(관계 사실성)
중립 문구 5/5 정판 — 관계 검증도 grounding 위에 올라탄다
판정 3값: fail(제약 위반 E코드) / hold(H201 식별 신뢰 낮음·LLM 결함·임계 미달) / pass. reject로 버리지 않고 hold로 보류 흐름시키는 것이 17.5.4·18.2절의 실패 원칙.
"모든 PR 자동 실행"은 아직 수동 — CI 자동화는 [제안](9장).
7 src/infra/ — 인프라 코드 [실재]
표준 역할: 클라우드 자원을 코드로 / 스토리지·웨어하우스·IAM·네트워킹 / apply 전 매번 plan 검토.
실물(Terraform 대신 셋업·검증 스크립트):
실물
표준 자리
내용·실측
setup-opensearch.sh
main.tf
로컬 OpenSearch 최초 설치·기동 — 전체 플러그인 배포(k-NN/neural/flow-framework)
start-opensearch.sh·start-kev.sh
(서비스 기동)
9200 엔진 / kev 검증기(GPU cuda+bf16, 로드 ~70초)
scripts/start·stop·status-emulator.ps1
(플랫폼 기동)
Windows→WSL 에뮬레이터 기동·중지·상태(localhost 포워딩 점검 포함)
test-pg-rls.sh
variables.tf(IAM 자리)
PG 18 제한 역할·RLS·읽기 전용·statement_timeout — 전 항목 통과: user_alpha는 ALPHA 1건만 노출, 소유자 우회 차단, 읽기전용 INSERT 거부, 타임아웃 취소, 역할별 기본 설정
t26-run.py + t26-templates.json
(웨어하우스 접근 계약)
제한 역할 sd_query(SELECT 전용·timeout 3s)·psql stdin·PGOPTIONS 세션 — 주입 4종·변조 템플릿·쓰기·장기질의 전부 차단 12/12. 역할 암호는 런타임 생성(.pgpass)
에뮬레이터가 대신 지는 클라우드 자원: S3(T07)·SQS/EventBridge(T27)·관리형 OpenSearch 도메인·정책(T10/T11/T16, BM25·별칭)·Lambda·KMS/Secrets·Glue·Athena·DMS 엔드포인트 — 단 k-NN DSL 질의·fgac 인증·Bedrock 추론은 미지원(노랑·빨강, 05·07호 판정).
plan 검토 대응: 규칙·기준판 버전 기록 후 적용(2.3절 원칙) — apply 전 plan 리뷰의 이 프로젝트식 번역. 에뮬레이터 리소스는 메모리 상주라 "apply"가 곧 재기동 재생성 — 상태 관리 파일(tfstate)에 해당하는 것은 원장 인덱스다.
8 .github/workflows/ — CI/CD [제안]
표준 역할: YAML로 파이프라인 정의 / 모든 PR에 lint·test·build / main 머지 시 배포.
실물 상태: 전 검증은 이미 재실행 가능한 스크립트 세트로 확보돼 있다 — CI로 싸는 일만 남았다: