From c3892fe0aa62fd463bf349c95512e293d933a913 Mon Sep 17 00:00:00 2001
From: Poia Assistant <poia@poi.local>
Date: Sat, 13 Jun 2026 14:25:52 +0900
Subject: [PATCH] feat: init POI Knowledge Portal with CI/CD workflow

---
 .gitea/workflows/mkdocs-build.yml | 34 ++++++++++++++++++++++++++
 architecture_design.md            | 26 ++++++++++++++++++++
 docs/index.md                     |  6 +++++
 mkdocs.yml                        | 40 +++++++++++++++++++++++++++++++
 4 files changed, 106 insertions(+)
 create mode 100644 .gitea/workflows/mkdocs-build.yml
 create mode 100644 architecture_design.md
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/.gitea/workflows/mkdocs-build.yml b/.gitea/workflows/mkdocs-build.yml
new file mode 100644
index 0000000..368f8a4
--- /dev/null
+++ b/.gitea/workflows/mkdocs-build.yml
@@ -0,0 +1,34 @@
+name: Build and Deploy MkDocs (POI Portal)
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          
+      - name: Install MkDocs and Plugins
+        run: |
+          pip install mkdocs-material
+          pip install mkdocs-multirepo-plugin
+          
+      - name: Build HTML Site
+        run: mkdocs build
+        
+      - name: Deploy to Nginx Document Root
+        # 주의: 실제 Nginx 호스팅 경로(예: /opt/data/nginx/html)로 복사하도록 추후 환경에 맞게 수정
+        run: |
+          echo "Build successful! Deploying site/ to target directory..."
+          # cp -r site/* /opt/data/nginx/html/poi-portal/
diff --git a/architecture_design.md b/architecture_design.md
new file mode 100644
index 0000000..6c23f51
--- /dev/null
+++ b/architecture_design.md
@@ -0,0 +1,26 @@
+# POI 통합 지식 포털 (POI Knowledge Portal) 설계서
+
+## 1. 시스템 목적
+- Loop Engineering을 통해 에이전트가 생성하는 일일 리포트 및 의사결정 요청 사항 통합 열람
+- Gitea에 분산되어 있는 여러 프로젝트(proxy_manager, ansel 등)의 설계/기술 문서를 단일 진입점(Portal)에서 제공
+- 마크다운 기반의 작성 편의성과 Material 디자인 기반의 미려한 HTML 웹사이트 열람 경험 동시 달성
+
+## 2. 아키텍처 및 기술 스택
+- **코어 엔진:** MkDocs
+- **UI/UX 테마:** Material for MkDocs (다크모드, 고성능 검색, 미려한 UI 제공)
+- **통합 플러그인:** `mkdocs-multirepo-plugin` (빌드 시점에 여러 Gitea 저장소의 문서를 동적으로 수집)
+- **다이어그램 엔진:** Mermaid.js (마크다운 텍스트를 시스템 구성도 이미지로 렌더링)
+- **배포 및 호스팅:** Gitea Actions(또는 Airflow) + Nginx 정적 웹 서버 호스팅
+
+## 3. 저장소 및 데이터 흐름 구조
+포털은 문서의 "소유권"을 각 팀과 에이전트에게 그대로 둡니다.
+
+1. **포털 뼈대 저장소 (`poi_knowledge_portal`)**
+   - 역할: 포털의 껍데기(UI 설정, 메뉴 구조)만 가짐
+2. **에이전트 리포트 저장소 (`loop-reports`)**
+   - 역할: Loop 시스템(에이전트)이 매일 상태를 마크다운으로 Commit
+3. **개별 프로젝트 저장소 (`project-A`, `project-B`)**
+   - 역할: 개발팀이 소스코드와 함께 `docs/` 폴더에 설계서 작성
+
+**동작 흐름(Workflow):**
+`에이전트/개발자 Commit` → `Webhook 트리거` → `MkDocs가 모든 저장소에서 문서 수집 및 HTML 빌드` → `Nginx 웹서버 갱신`
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..e2f1bc9
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,6 @@
+# 환영합니다! POI 통합 지식 포털입니다.
+
+이곳은 POI 시스템의 모든 아키텍처 설계서와 에이전트(Loop) 리포트가 모이는 중앙 지식 저장소입니다.
+
+- **Loop Report**: 에이전트들이 처리한 자동화 업무, 승인 대기 항목을 확인하세요.
+- **프로젝트 설계서**: Gitea에 분산된 각 프로젝트의 최신 설계 문서를 열람하세요.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..370700b
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,40 @@
+site_name: POI Knowledge Portal
+site_description: POI 시스템 설계 문서 및 Loop Engineering 리포트 통합 포털
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - search.suggest
+
+plugins:
+  - search
+  # - multirepo: 
+  #     repos:
+  #       - section: "1. Loop 리포트"
+  #         import_url: https://gitea.local/loop-reports?docs_dir=docs/*
+  #       - section: "2. 프로젝트 설계서"
+  #         import_url: https://gitea.local/proxy_manager?docs_dir=docs/*
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - md_in_html
+  - tables
+  - admonition
+
+nav:
+  - 홈: index.md