How laguna821/beompis_preview_3_combo works
프로젝트 타입/목적 식별 (이 다이어그램의 “정답 범위”)
이 프로젝트는 백엔드/서버가 없는 단일 HTML 로컬 웹앱(오프라인-first) 입니다.
• 목적: 범정부오피스 “G서식 변신” 규칙 기반 텍스트를 붙여넣으면, 브라우저에서 HWP 보고서 스타일로 즉시 렌더링(미리보기) 하여 *내용(논리 흐름) 검토*에 집중하게 하는 도구
• 실행 형태: ...미리보기 앱__v_*.html 파일을 더블클릭 → 브라우저에서 실행
• 데이터 처리: 네트워크 없이 브라우저 내부에서만 처리, 상태는 localStorage에 저장
• AI(GPT-5/Gemini)는 “연동되는 외부 API”라기보다, 사용자가 생성한 텍스트를 입력으로 붙여넣는 워크플로우 상의 외부 생산자에 가까움
따라서 시스템 설계 다이어그램은 “클라우드/마이크로서비스” 중심이 아니라,
브라우저 내부 모듈 설계(파서/렌더러/상태/프린트 등) + 사용자 워크플로우(한글/HWP로 복사-붙여넣기) 중심으로 그리는 것이 가장 정확합니다.
파일 구조 기반 아키텍처 해석
최상위 파일 트리에서 핵심은 아래 3종류입니다.
실행물
• 범정부오피스 G서식변신_미리보기 앱__v_4_*.html
• 범정부오피스 G서식변신_미리보기 앱__v_6_*.html
→ 단일 HTML 안에 UI/CSS/JS 로직이 모두 들어있는 monolith SPA 가능성이 큼(프레임워크 흔적 없음)
프롬프트/지침 문서
• 범정부오피스 G서식변신봇 프롬프트 (short/long).txt
• [GPTs Instructions – ...].txt
→ 앱의 기능은 “프롬프트 결과를 붙여넣어 렌더링”이므로, 이 문서들은 외부 입력 생성 규격(계약/프로토콜) 역할
README
• 기능: 토큰 정리, HWP 스타일 모사, 접기/펼치기, 통계/경고, 인쇄/PDF, Shift+Click 단일 보기
• 저장: localStorage
• 개인정보 외부 전송 없음(중요한 보안/데이터 흐름 포인트)
다이어그램을 그릴 때의 “메인 컴포넌트” 쪼개기 (가능한 한 세분화)
이 프로젝트는 단일 HTML이지만, 시스템 다이어그램에서는 내부를 모듈로 분해해서 그려야 정확해집니다.
Actor / External System (외부 주체/시스템)
• User(작성자)
• AI 텍스트 생성 도구(GPT-5, Gemini, NotebookLM 등): *옵션/외부 생산자*
• 실제 통신이 없다면 “외부 입력 공급원(Out-of-band)”로 표기
• 범정부오피스/한글(HWP) 환경: 최종 붙여넣기 및 “G서식 변신” 실행 주체
• 앱 관점에서는 “Export Target(수동 복사/붙여넣기)” 시스템
Runtime Container (실행 컨테이너)
• Web Browser (Chrome/Edge/Safari)
• 이 브라우저가 사실상 “애플리케이션 서버 + UI 런타임” 역할
App 내부 컴포넌트 (단일 HTML 내부 모듈)
README 기능을 기준으로 최소 아래로 분해해서 그리면 좋습니다.
Input Editor / Source Pane
• G서식 텍스트 입력(붙여넣기)
• “소프트 줄바꿈” 표시 로직(표시-only wrap)
Token Normalizer (토큰 자동 정리)
• 제목 : → 제목: 등 공백/전각콜론 정규화
• “정리 버튼” 트리거 및 정리 결과를 소스에 반영
Parser / Block Builder
• 토큰(제목:, 배경:, 소제목:, 네모:, 원:, 바:, 당구장:, 별: 등)를 인식
• 텍스트를 블록/섹션 트리(장/소제목/본문)로 구조화
Validator / Linter (통계/경고)
• 누락 토큰 감지, 블록 개수 카운트, 장/소제목 개수 등
• UI에 경고 배지/요약 통계 출력
Renderer (HWP Style Mimic)
• 파서 결과(구조 트리)를 DOM으로 렌더
• 스타일 맵핑(제목=하늘색 박스, 배경=흰 박스, 소제목=네이비 라벨 등)
• 라이트/다크 모드 CSS 적용
Outline / Collapse Controller (접기/펼치기)
• 장 단위 접기/펼치기
• 소제목 단위 접기/펼치기
• Shift+Click 단일 보기(해당 장만 펼치고 나머지 접기)
Export / Print Module
• 인쇄/PDF 내보내기: 브라우저 Print API(window.print) 기반일 가능성이 큼
• “입력 복사” 기능: Clipboard API 또는 selection 기반
Persistence (localStorage State)
• 마지막 입력, UI 상태(다크모드, 접힘 상태 등) 저장/복원
컴포넌트 간 관계/상호작용(화살표로 반드시 표현해야 하는 데이터 흐름)
다이어그램에서 핵심 플로우는 아래 2개입니다.
(옵션) State → localStorage: 자동 저장
이 파이프라인을 다이어그램에서 한 줄로 단순화하지 말고, 최소 “정리→파싱→검증→렌더” 4단계로 분리하면 설계가 훨씬 정확해집니다.
User → 범정부오피스 기능: “G서식 변신” 실행(앱 외부)
여기서 중요한 설계 포인트는 “앱이 HWP와 API로 통신하는 것이 아니라, 사용자가 클립보드로 이동시키는 ‘휴먼-인-더-루프’ 통합”이라는 점입니다. 다이어그램에서 이를 점선 화살표/Manual step으로 명확히 표시하세요.
이 프로젝트는 작지만, C4 모델로 2~3장 그리면 “정확도”와 “가독성”이 동시에 나옵니다.
(1) C4 Level 1: System Context (업무 흐름 중심)
포함 요소:
• User
• AI Text Generator(외부)
• G서식 미리보기 앱(본 시스템)
• HWP/범정부오피스(외부)
• 로컬 디바이스/브라우저(실행 환경을 경계로 표시)
관계:
• AI → User: G서식 텍스트 생성(Out-of-band)
• User → App: paste/편집
• App → User: preview/검증 피드백
• User ↔ HWP: copy/paste & 변신 실행
(2) C4 Level 2: Container (여기서는 “브라우저 내부 앱 + 저장소”가 컨테이너)
컨테이너를 과감히 분리:
• Browser Runtime (Container)
• Single-HTML App (JS/CSS/DOM)
• localStorage (Browser storage)
외부:
• Clipboard(브라우저 기능)
• Print/PDF(브라우저 print subsystem)
(3) C4 Level 3: Component (가장 중요한 장)
단일 HTML 내부를 아래 컴포넌트로 박스 분해:
• Input Editor
• Token Normalizer
• Parser/Block Builder
• Validator/Linter
• Renderer(Theme 포함)
• /Collapse Controller
• Export/Print
• Persistence(localStorage adapter)
그리고 각 컴포넌트 사이 데이터 구조를 라벨링:
• “Raw G-text”
• “Normalized G-text”
• “Document AST / Block Tree”
• “Warnings/Stats”
• “Rendered DOM”
기술/프레임워크/라이브러리 표기 가이드 (README/구조 기준)
• 핵심 기술: HTML/CSS/JavaScript in-browser
• 저장: localStorage
• 출력: window.print() / PDF(브라우저)
• 복사: Clipboard API(가능성) 또는 DOM selection
• 네트워크: 없음(Offline) — 다이어그램에 “No backend / No external calls” 명시
• 만약 HTML 내부에 CDN 링크가 있다면(현재 정보로는 불명), 그때만 “Optional CDN dependency”로 별도 표기
박스/색상(예시)
• 파란색: UI 컴포넌트 (Input Editor, Preview Pane, Outline Controller)
• 초록색: 순수 로직(Tokenizer/Parser/Validator)
• 보라색: 브라우저 기능/플랫폼(Clipboard, localStorage, Print)
• 회색: 외부 시스템(AI, HWP/범정부오피스)
화살표 규칙
• 실선: 앱 내부 자동 처리(실시간 파이프라인)
• 점선: 수동 단계(사용자 copy/paste), 또는 “옵션 입력원(AI)”
• 화살표 라벨: 반드시 “데이터 타입”을 적기
예) G서식 텍스트, 정규화 텍스트, 블록 트리, 경고/통계, 렌더 DOM
경계(Trust/Privacy Boundary)
• “Local machine boundary”를 그어:
• 그 안: Browser + App + localStorage (데이터가 절대 밖으로 안 나감)
• 밖: AI 서비스, HWP, 조직 시스템
이 경계 표시는 README의 “외부 전송 없음”을 설계적으로 증명해줍니다.
“최대한 정확한” 다이어그램을 위해 추가로 확인하면 좋은 체크리스트
• HTML이 CDN 의존성(예: Tailwind/Bootstrap/JS lib) 있는지?
• localStorage에 저장하는 키(입력 텍스트/테마/접힘 상태 등) 범위는?
• 파서가 만드는 구조가 단순 리스트인지, “장/소제목 트리”인지?
• 인쇄/PDF가 단순 print CSS인지, 별도 “print layout renderer”가 있는지?
• 에러 처리: 잘못된 토큰/누락 토큰 시 렌더러가 어떻게 degrade 되는지?
이 체크리스트 결과에 따라 Component 다이어그램에서 “Dependencies/Edge cases” 박스를 더 쪼개면 됩니다.
최종적으로 그리면 좋은 “한 장짜리 요약 아키텍처(추천 구성)”
한 장에 담는다면 아래 구조가 가장 이 프로젝트에 맞습니다.
• 좌측: Actor/External (User, AI text, HWP)
• 중앙: Browser Container
• Input Editor
• Token Normalizer
• Parser
• Validator/Stats
• Renderer + Theme
• /Collapse
• Export/Print
• localStorage adapter
• 우측: Preview Output + Print/PDF + Clipboard
• 하단/상단: “Offline / No network” 배너 + Local boundary 표시
이렇게 그리면 “단일 HTML 앱”임에도 불구하고, 기능/데이터 흐름/통합 지점이 모두 드러나는 가장 정확한 시스템 설계 다이어그램이 됩니다.