landing_page/README.md

🌐 경북대학교 AI 에이전트 네트워크 연구실 (ANL) 공식 웹사이트

AI Agent Networking Laboratory (ANL), School of Computer Science and Engineering, Kyungpook National University

본 리포지토리는 경북대학교 컴퓨터학부 AI 에이전트 네트워크 연구실의 공식 웹사이트 및 데이터 관리 대시보드 시스템입니다. 실시간 런타임 데이터 동기화를 지원하는 Next.js 14+ 프론트엔드, Go (Gin) 고성능 RESTful 백엔드, SQLite 트랜잭션 데이터베이스, 그리고 통합 Docker 컨테이너 오케스트레이션으로 구축되었습니다.

---

📌 1. 연구실 개요 및 핵심 연구 분야 (Lab Overview & Research Focus)

• 연구실명: AI 에이전트 네트워크 연구실 (ANL / AI Agent Networking Laboratory)
• 소속: 경북대학교 IT대학 컴퓨터학부
• 지도교수: 고석주 교수 (Prof. Seok-Joo Koh / sjkoh@knu.ac.kr)
• 연구 패러다임:
  • Present & Future: MCP & SKILL, 멀티에이전트 오케스트레이션 (HERDR, crewAI, LangGraph), 이종 에이전트 상호운용성 표준 (ACP, A2A), 및 AIoT gRPC/QUIC 고성능 통신 백본

---

💡 2. 핵심 연구 분야 (Core Research Areas)

🔌 1) AI Agent 기능 확장 프로토콜 (MCP & SKILL)

• MCP (Model Context Protocol): Anthropic 제정 오픈 규격으로 도구, 데이터 리소스, 프롬프트 표준 인터페이스 연동
• SKILL (자율 확장 도구 패키지): 실행 코드 + 도구 명세 + Few-shot이 결합된 모듈형 에이전트 기능 확장
• CLI 자율 코딩 에이전트: Claude Code, Antigravity CLI 등 터미널 기반 자율 소프트웨어 엔지니어링

🤖 2) 멀티 에이전트 협업 및 오케스트레이션 (Multi-Agent Orchestration)

• 이종 에이전트 교차 검증: 서로 다른 LLM 모델(Planner, Creator, Reviewer) 간 비평/합의 루프로 무결성 확보
• 오케스트레이션 인프라 코어:
  • HERDR: 가상 백그라운드 프로세스 격리 및 에이전트 세션 TUI 관제
  • LangGraph & crewAI: 상태 보존형 순환 그래프, 역할 기반 분업 및 예외 롤백 처리

🌐 3) 에이전트 상호운용성 개방형 표준 (Agent Interoperability: ACP & A2A)

• ACP (Agent Communication Protocol): IBM Research 제정 서비스 발견 및 태스크 위임 오픈 표준
• A2A (Agent-to-Agent Protocol): Google/Linux Foundation 주도 이종 에이전트 간 표준 메시지 교환 통신 표준
• Agent Card (/.well-known/agent-card.json): 에이전트 역량(Capabilities) 및 보안 사양 표준 프로필

⚡ 4) 지능형 사물인터넷 (AIoT) & 고성능 백본 (AIoT & gRPC/QUIC)

• AIoT 분산 자율 제어: 센서 계층과 엣지 연산 계층 간 멀티 에이전트 분산 배치
• gRPC & QUIC 양방향 스트리밍: HTTP/2 & HTTP/3 기반 고속 바이너리 멀티모달 전송

---

🏗️ 3. 시스템 아키텍처 (System Architecture)

graph TD
    User["🌐 User / Browser"]
    Admin["👑 Admin User"]

    subgraph Docker_Network ["Docker Bridge Network (anl-net)"]
        subgraph Frontend_App ["Next.js 14 Frontend (anl-frontend:3000)"]
            PublicPages["Public Pages (force-dynamic)<br/>/, /members, /publications, /lectures, /standardization"]
            AdminConsole["Admin Dashboard (/console)<br/>Research Projects, Areas, Members, Pubs, Lectures, Standards"]
            API_Client["Typed API Client (lib/api.ts, lib/adminApi.ts)"]
        end

        subgraph Backend_App ["Go Gin Backend API (anl-backend:8080)"]
            Router["REST API Router & CORS"]
            AuthMW["RequireAdminToken Middleware"]
            Handlers["CRUD Handlers (Home, Members, Pubs, Lectures, Standards)"]
            Repo["Repository Layer & Transaction Order Normalizer"]
        end

        subgraph Storage ["Persistent Volume Storage (anl-sqlite-storage)"]
            SQLiteDB[("SQLite Database<br/>/app/data/anl.db")]
        end
    end

    User -->|HTTP :3000| PublicPages
    Admin -->|Bearer Auth :3000| AdminConsole
    PublicPages --> API_Client
    AdminConsole --> API_Client
    API_Client -->|REST API :8080| Router
    Router --> AuthMW
    AuthMW --> Handlers
    Handlers --> Repo
    Repo --> SQLiteDB

---

📁 4. 디렉터리 구조 (Directory Structure)

landing_page/
├── README.md                      # [본 문서] 종합 프로젝트 가이드 및 배포/운영 문서
├── docker-compose.yml             # 통합 Docker Compose 멀티 서비스 오케스트레이션
├── .env.example                   # 환경변수 설정 템플릿
│
├── backend/                       # ⚡ [Go 백엔드 REST API]
│   ├── cmd/                       # 진입점 (api: API 서버, seed: 시더, export-content)
│   ├── internal/                  # 비즈니스 로직 (handlers, repository, router, config, httpx)
│   ├── db/backup/                 # 💾 데이터베이스 백업 (anl.db 바이너리, anl_dump.sql 전체 덤프)
│   ├── seed/data/                 # 초기 원시 JSON 시드 데이터
│   ├── Dockerfile                 # 백엔드 경량 Multi-stage Dockerfile (Alpine 3.20)
│   ├── Makefile                   # 빌드, 테스트, 포맷, 백업(make backup-db) 타겟
│   └── go.mod                     # Go 모듈 의존성 정의
│
├── refer_landing_page/            # 🚀 [Next.js 14 프론트엔드 & 관리자 콘솔]
│   ├── app/                       # App Router 페이지 (공개 페이지 및 /console 관리자 대시보드)
│   ├── components/                # UI 컴포넌트 (Header, Footer, Reveal, Counter, Marquee 등)
│   ├── lib/                       # API 통신 클라이언트 (api.ts: 조회, adminApi.ts: CRUD)
│   ├── docs/                      # 디자인 시스템 (DESIGN.md: Issue 01 에디토리얼 스타일)
│   ├── scripts/                   # E2E 테스트 스위트 및 데이터 검증 러너
│   ├── Dockerfile                 # 프론트엔드 Standalone Multi-stage Dockerfile (Node 20 Alpine)
│   ├── next.config.js             # output: "standalone" 프로덕션 번들링 설정
│   └── package.json               # Next.js, React, Tailwind CSS 의존성
│
├── .agents/                       # 🤖 멀티 에이전트 오케스트레이션 스킬 & 룰셋 (MAM)
├── .mam/                          # ⚡ 에이전트 세션 DB 및 HERDR 격리 레지스트리
└── ISL-2026/                      # 📄 레거시 실측 원본 HTML/CSS 아카이브

---

🚀 5. Docker 컨테이너 배포 및 운영 가이드 (Production Deployment)

다른 워크스테이션이나 서버에서 Docker를 통해 원클릭으로 전체 시스템을 빌드하고 배포하는 방법입니다.

1) 저장소 클론 및 환경 설정

# 1. 저장소 클론
git clone <리포지토리_URL> landing_page
cd landing_page

# 2. 환경변수 파일 생성
cp .env.example .env

# (선택) .env 파일에서 관리자 토큰(ADMIN_TOKEN) 및 포트 변경 가능

2) 컨테이너 이미지 빌드

# 프론트엔드 및 백엔드 이미지 동시 빌드
docker compose build

# (선택) 캐시 없이 전체 재빌드 시
docker compose build --no-cache

3) 서비스 백그라운드 배포 및 실행

# 1. 컨테이너 백그라운드 실행
docker compose up -d

# 2. 실행 상태 및 헬스체크 확인 (anl-backend-api 및 anl-frontend-app)
docker compose ps

# 3. 실시간 로그 모니터링
docker compose logs -f

4) 서비스 접속 URL

• 🌐 공식 홈페이지: http://localhost:3000
• 👑 관리자 대시보드: http://localhost:3000/console (로그인 토큰: .env에 설정된 ADMIN_TOKEN)
• ⚡ 백엔드 REST API: http://localhost:8080/api/v1
• 💓 API 헬스체크: http://localhost:8080/api/v1/health

5) 컨테이너 관리 및 중지

# 서비스 재시작
docker compose restart

# 서비스 중지 및 컨테이너 제거 (데이터베이스 볼륨은 안전하게 보존됨)
docker compose down

# (주의) 데이터베이스 볼륨까지 완전히 삭제하고 초기화할 때
docker compose down -v

---

🛠️ 6. 로컬 개발 및 실행 가이드 (Getting Started)

Docker 없이 로컬 개발 환경에서 프론트엔드와 백엔드를 각각 직접 실행하고 개발하는 방법입니다.

🅰️ Backend (Go REST API) 개발 가이드

사전 요구사항

• Go 1.22+ (권장: Go 1.26+)
• SQLite 3
• Make 빌드 도구

실행 절차

# 1. 백엔드 디렉터리로 이동
cd backend

# 2. 환경 설정 파일 복사
cp .env.example .env

# 3. Go 모듈 의존성 다운로드
go mod download

# 4. 데이터베이스 백업본 복원 (최신 실측 데이터 223건 적재)
sqlite3 anl.db < db/backup/anl_dump.sql

# 5. 백엔드 API 서버 빌드 및 실행 (기본 포트: http://localhost:8080)
make run

# 6. (별도 터미널) 유닛 테스트 및 코드 품질 검사
make test       # 유닛 테스트 실행
make fmt-check  # gofmt 포맷 검사
make vet        # go vet 정적 분석

---

🅱️ Frontend (Next.js 14+) 개발 가이드

사전 요구사항

• Node.js 20+ (LTS)
• npm 10+

실행 절차

# 1. 프론트엔드 디렉터리로 이동
cd refer_landing_page

# 2. 의존성 패키지 설치
npm install

# 3. 로컬 환경변수 파일 설정 (필요 시)
# 기본값으로 http://localhost:8080/api/v1에 자동 연결됩니다.
echo "NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/api/v1" > .env.local

# 4. 개발 서버 실행 (기본 포트: http://localhost:3000)
npm run dev

# 5. 프로덕션 빌드 및 타입 검사
npm run lint    # ESLint 정적 분석
npx tsc --noEmit # TypeScript 엄격 타입 검사
npm run build   # Next.js Standalone 프로덕션 빌드

# 6. 전체 통합 E2E 테스트 스위트 실행 (Gate 0~11 자동 검증)
python3 scripts/run_e2e_tests.py

---

💾 7. 데이터베이스 백업 및 복원 가이드 (Database Backup & Restore)

연구실의 소중한 논문, 특허, 멤버, 강의, 표준화 데이터는 SQLite 데이터베이스를 통해 관리되며, 손쉬운 백업/복원 도구를 제공합니다.

1) 백업 파일 구성 (backend/db/backup/)

• anl.db: SQLite 바이너리 온라인 스냅샷 파일
• anl_dump.sql: 스키마 DDL 및 전체 11개 테이블 데이터 INSERT문이 포함된 표준 SQL 텍스트 덤프 (Git 추적 관리)

2) 데이터베이스 즉시 백업 명령어

언제든지 백엔드 디렉터리에서 명령어 한 줄로 최신 상태를 백업할 수 있습니다:

cd backend
make backup-db

3) 신규 환경 또는 Docker 컨테이너 복원 방법

🐳 Docker 배포 환경에서 복원 (추천)

docker compose exec -T anl-backend sqlite3 /app/data/anl.db < backend/db/backup/anl_dump.sql

💻 로컬 개발 환경에서 복원

cd backend
sqlite3 anl.db < db/backup/anl_dump.sql

---

👑 8. 관리자 대시보드 (/console) 사용 가이드

연구실 홈페이지의 모든 데이터를 웹 UI에서 실시간으로 추가, 수정, 삭제할 수 있는 관리자 콘솔을 지원합니다.

1. 접속 경로: http://localhost:3000/console/login
2. 관리자 인증:
   • 백엔드 .env 파일에 정의된 ADMIN_TOKEN (기본값: anl-admin-secret-token-2026)을 입력하여 로그인합니다.
   • 인증 토큰은 브라우저 세션에 저장되며, 모든 변조 요청(POST, PUT, DELETE)에 Authorization: Bearer <TOKEN> 헤더로 자동 첨부됩니다.
3. 제공 기능:
   • 주요 연구 과제 (/console/research-projects): 과제명, 기간, 주관기관, 연구비 등 CRUD
   • 핵심 연구 분야 (/console/research-areas): 연구 분야 CRUD 및 순서 변경 시 1..N 자동 정규화 & 시프트
   • 구성원/졸업생 (/console/members): 교수, 연구원, 졸업생 인적사항, 연구분야, 취업처 CRUD
   • 논문/특허 실적 (/console/publications): 국외/국내 학술지 및 학술대회, 특허 실적 223건 CRUD
   • 강의 자료실 (/console/lectures): 학기별 개설 과목, 강의 개요, 다운로드 링크 관리
   • 표준화 기구 (/console/standardization): oneM2M, ITU-T 등 기구별 표준 문서 번호 및 상태 관리

---

👥 9. 멀티 에이전트 오케스트레이션 프로토콜 (MAM)

본 프로젝트는 Multi-Agent Mux (MAM) 기반의 자율 에이전트 협업 루프를 통해 개발 및 유지보수됩니다.

에이전트 세션명	담당 역할 (Role)	도구/런타임	주요 임무
🧠 planner-reviewer-claude-01	planner and reviewer	Claude Code	아키텍처 설계, 구현 계획 수립, 데이터 무결성 검증, 최종 PASS 판정
🎨 creator-agy-01	creator	Antigravity CLI	컴포넌트 개발, 백엔드 API 구현, Docker 컨테이너화, 리팩토링
🔍 reviewer-cline-01	reviewer	Cline	웹 표준/SEO 검수, 타입 안전성, Docker 네트워크/보안 심층 코드 리뷰

• 자율 루프 실행: bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh --all-reviewer --target-agent "creator-agy-01" --task "<작업내용>"
• 세션 상태 확인: bash .agents/skills/multi-agent-mux-status/scripts/status.sh