# laguna821/beompis_preview_3_combo architecture

> Architecture diagram of the GitHub repository laguna821/beompis_preview_3_combo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laguna821/beompis_preview_3_combo
- Repository: https://github.com/laguna821/beompis_preview_3_combo

## Overview

##### 프로젝트 타입/목적 식별 (이 다이어그램의 “정답 범위”)
이 프로젝트는 **백엔드/서버가 없는 단일 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 앱”임에도 불구하고, 기능/데이터 흐름/통합 지점이 모두 드러나는 **가장 정확한 시스템 설계 다이어그램**이 됩니다.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% SYSTEM CONTEXT + CONTAINER + COMPONENT (1-page summary)
  %% Vertically oriented, offline-first, single HTML local app
  %% =========================================================

  %% --------- External / Actors ----------
  subgraph "External Actors & Systems (Out-of-band / Manual)"
    direction TB
    User["User (작성자)"]:::external
    AI["AI Text Generator\n(GPT-5/Gemini/NotebookLM 등)\nOut-of-band producer"]:::external
    HWP["범정부오피스 / 한글(HWP)\nExport Target\n(G서식 변신 실행)"]:::external
    PromptLong["Prompt/Spec (Long)\nExternal input contract"]:::doc
    PromptShort["Prompt/Spec (Short)\nExternal input contract"]:::doc
    GPTInstr["GPTs Instructions\nUsage spec / guidance"]:::doc
  end

  %% --------- Trust / Privacy Boundary ----------
  subgraph "Local Machine Boundary (Offline-first / No network calls)"
    direction TB

    subgraph "Web Browser Runtime (Chrome/Edge/Safari)"
      direction TB

      App["Single-HTML Preview App\n(UI/CSS/JS Monolith SPA)"]:::app

      subgraph "App Components (inside single HTML)"
        direction TB

        Input["Input Editor / Source Pane\n(paste/edit, soft-wrap indicator)"]:::ui
        Normalizer["Token Normalizer\n(공백/전각콜론 정규화)"]:::logic
        Parser["Parser / Block Builder\n(token recognition → section tree)"]:::logic
        Validator["Validator / Linter\n(warnings, stats)"]:::logic
        Renderer["Renderer (HWP style mimic)\n+ Theme (Light/Dark)"]:::ui
        Outline["Outline / Collapse Controller\n(chapter/section fold, Shift+Click isolate)"]:::ui
        Preview["Preview Pane (Rendered DOM)"]:::ui
        Export["Export / Print Module\n(copy input, print/PDF)"]:::ui
        Persistence["Persistence Adapter\n(state save/restore)"]:::logic
      end

      LS[("localStorage\n(browser storage)")]:::platform
      Clipboard["Clipboard (Browser feature)"]:::platform
      PrintSys["Print / PDF Subsystem\n(window.print)"]:::platform
      Readme["README\n(features/behavior spec)"]:::doc
    end
  end

  %% --------- Context relationships (manual / out-of-band) ----------
  AI -.->|"generated_G-text"| User
  PromptLong -.->|"defines_format"| AI
  PromptShort -.->|"defines_format"| AI
  GPTInstr -.->|"workflow_guidance"| User
  Readme -.->|"usage_reference"| User

  User -->|"paste/edit_G-text"| Input
  Renderer -->|"preview+feedback"| User
  Validator -->|"warnings/stats_UI"| User

  %% --------- Real-time rendering pipeline (internal, solid) ----------
  Input -->|"Raw_G-text"| Normalizer
  Normalizer -->|"Normalized_G-text"| Parser
  Input -->|"Raw_G-text (optional_direct)"| Parser
  Parser -->|"Document_AST/Block_Tree"| Validator
  Parser -->|"Document_AST/Block_Tree"| Renderer
  Validator -->|"Warnings/Stats"| Renderer
  Renderer -->|"Rendered_DOM"| Preview
  Outline -->|"toggle_visibility"| Preview
  Renderer -->|"section_nodes"| Outline

  %% --------- Persistence (internal) ----------
  Input -->|"draft_text+UI_state"| Persistence
  Outline -->|"collapse_state"| Persistence
  Renderer -->|"theme_state"| Persistence
  Persistence -->|"save/load"| LS
  Persistence -->|"restore_state"| Input
  Persistence -->|"restore_state"| Outline
  Persistence -->|"restore_state"| Renderer

  %% --------- Export / Print workflow (manual + browser subsystems) ----------
  User -->|"click_copy/print"| Export
  Export -->|"copy_to_clipboard"| Clipboard
  Export -->|"window.print()"| PrintSys
  User -.->|"manual_paste"| HWP
  Clipboard -.->|"manual_transfer"| HWP
  User -.->|"run_G서식변신"| HWP

  %% --------- Explicit note: no network ----------
  App ---|"Offline_only\nNo_backend / No_external_calls"| LS

  %% --------- Click Events (from component mapping) ----------
  click App "https://github.com/laguna821/beompis_preview_3_combo/blob/main/범정부오피스 G서식변신_미리보기 앱__v_4_ACH_10-14-2025.html"
  click App "https://github.com/laguna821/beompis_preview_3_combo/blob/main/범정부오피스 G서식변신_미리보기 앱__v_6_ACH_11-28-2025.html"
  click PromptLong "https://github.com/laguna821/beompis_preview_3_combo/blob/main/범정부오피스 G서식변신봇 프롬프트 (long text).txt"
  click PromptShort "https://github.com/laguna821/beompis_preview_3_combo/blob/main/범정부오피스 G서식변신봇 프롬프트 (short text).txt"
  click GPTInstr "https://github.com/laguna821/beompis_preview_3_combo/blob/main/[GPTs Instructions – 범정부오피스 표 자동 생성 헬퍼].txt"
  click Readme "https://github.com/laguna821/beompis_preview_3_combo/blob/main/README.md"

  %% --------- Styles ----------
  classDef external fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440
  classDef doc fill:#F3F0FF,stroke:#6C5CE7,stroke-width:1px,color:#2D3436
  classDef app fill:#FFEAA7,stroke:#B7791F,stroke-width:2px,color:#2D3436
  classDef ui fill:#D6EAF8,stroke:#1B4F72,stroke-width:1.5px,color:#1B2631
  classDef logic fill:#D5F5E3,stroke:#1E8449,stroke-width:1.5px,color:#0B3D2E
  classDef platform fill:#E8DAEF,stroke:#6C3483,stroke-width:1.5px,color:#2D1238
```
