poi-knowledge-portal/architecture_design.md

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 웹서버 갱신