landing_page/ARCHITECTURE.md

AI Agent Networking Lab (ANL) — System Architecture Specification

1. System Overview

AI Agent Networking Lab (ANL) 시스템은 연구실의 학술 실적(논문, 특허), 연구 과제, 구성원, 강의, 표준화 기고서 등의 데이터를 효율적으로 관리하고 제공하기 위한 **하이브리드 데이터 아키텍처(Decoupled Static-Export & Headless API Architecture)**로 설계되었습니다.

Next.js 기반의 고성능 정적 웹사이트(SSG)와 Go/Gin 및 SQLite 기반의 독립형 헤드리스(Headless) 백엔드 API 서버를 분리하여, **완벽한 정적 빌드 성능(0 Dynamic Route)**과 단일 진실 공급원(Single Source of Truth) 기반의 데이터 관리 편의성을 동시에 달성합니다.

---

2. High-Level Architecture Diagram

graph TD
    subgraph "Storage & Ingestion Layer"
        SEED["Seed Data JSON<br/>(backend/seed/data/*.json)"] -->|cmd/seed| SQLITE[("SQLite Database<br/>(anl.db - WAL Mode)")]
        SQLITE -->|cmd/export-content| TS_CONTENT["Static TypeScript Content<br/>(refer_landing_page/content/*.ts)"]
    end

    subgraph "Backend API Serving Layer (Go / Gin)"
        API_MAIN["API Server Binary<br/>(backend/cmd/api)"] --> ROUTER["Gin Engine & Router<br/>(internal/router)"]
        ROUTER --> HANDLERS["Domain Handlers<br/>(internal/handlers)"]
        HANDLERS --> REPO["Repository Layer<br/>(internal/repository)"]
        REPO -->|database/sql + modernc.org/sqlite| SQLITE
    end

    subgraph "Frontend Presentation Layer (Next.js 14 SSG)"
        TS_CONTENT --> NEXT_BUILD["Next.js Static Build Engine<br/>(○ Static / ● SSG)"]
        NEXT_BUILD --> SSG_PAGES["Static HTML Routes<br/>(/, /members, /publications, etc.)"]
        ADMIN["Future Admin Dashboard<br/>(CRUD Client)"] -.->|REST API /api/v1| ROUTER
        CLIENT_BROWSER["End Users / Browsers"] -->|Fast CDN / Nginx Serving| SSG_PAGES
    end

---

3. Core Architectural Principles

3.1 Single Source of Truth (SSOT)

• 모든 연구실 데이터(과제, 멤버, 논문, 특허, 강의, 표준화)는 **SQLite 데이터베이스(anl.db)**를 단일 원천으로 관리합니다.
• 데이터 갱신 시 cmd/export-content 도구를 통해 프론트엔드의 content/*.ts 파일로 동기화되어 코드와 데이터의 정합성을 보장합니다.

3.2 Zero-CGO Pure Go & Portability

• SQLite 드라이버로 **modernc.org/sqlite**를 채택하여 CGO 의존성을 완전히 제거했습니다.
• C 컴파일러 없이도 단일 실행 바이너리(bin/api, bin/seed, bin/export-content)로 컴파일되며, macOS, Linux, Docker 컨테이너 등 어떤 환경에서도 즉시 구동됩니다.

3.3 High-Performance Read Optimization (WAL Mode)

• 랜딩페이지 특성상 읽기(Read) 요청이 99% 이상이므로, SQLite 연결 시 WAL(Write-Ahead Logging) 모드와 busy_timeout=5000을 적용하여 동시 다발적인 읽기 트랜잭션에서 잠금 경합 없는 고속 처리를 보장합니다.

3.4 Strict Static Build Compliance (DM-03 / AC-17)

• 프론트엔드 빌드 시 런타임 API 호출 의존성을 배제하여 Next.js 정적 사전 렌더링(○ Static / ● SSG) 원칙을 100% 준수합니다.

---

4. Layered Module Structure

backend/
├── cmd/
│   ├── api/main.go                 # Gin HTTP REST API 서버 엔드포인트 (:8080)
│   ├── seed/main.go                # SQLite DDL 마이그레이션 및 JSON 시드 데이터 인제스트 도구
│   └── export-content/main.go      # SQLite DB 데이터를 프론트엔드 content/*.ts 파일로 내보내는 도구
├── internal/
│   ├── db/
│   │   ├── db.go                   # SQLite 커넥션 풀 관리 및 PRAGMA 설정 (WAL, foreign_keys)
│   │   └── migrations/             # golang-migrate SQL DDL 스크립트 (000001_init.up.sql / down.sql)
│   ├── models/                     # 도메인별 데이터 구조체 모델
│   │   ├── home.go                 # ResearchProject, ResearchArea, StatsSummary
│   │   ├── members.go              # Member, Alumnus
│   │   ├── publications.go         # Publication, Patent
│   │   ├── lectures.go             # Semester, Course
│   │   └── standardization.go      # StandardsBody, StandardProject, StandardDocument
│   ├── repository/                 # database/sql 기반 비즈니스 쿼리 계층 (N+1 방지 일괄 쿼리 최적화)
│   ├── handlers/                   # Gin HTTP 요청 바인딩 및 JSON 응답 핸들러
│   ├── router/                     # API 라우트 등록, CORS 미들웨어 및 통합 테스트
│   └── httpx/                      # 표준 JSON 응답 봉투 ({ data: ... } / { error: ... })
├── seed/data/                      # 손실 없이 추출된 원본 JSON 데이터셋
└── Makefile                        # 빌드, 테스트, 시드, 실행 자동화 타겟

---

5. Data Flow Workflows

5.1 Initial Seeding & Database Bootstrap

1. make seed 실행
2. cmd/seed가 SQLite 데이터베이스 파일(anl.db)을 생성
3. 임베디드된 마이그레이션 DDL(000001_init.up.sql)을 실행하여 11개 테이블과 인덱스 생성
4. seed/data/*.json 파일들을 읽어 트랜잭션 내에서 일괄 삽입
5. 각 테이블별 행(Row) 개수 및 5대 대표 논문(is_highlight=1) 정합성을 자동 검증

5.2 Content Export & Frontend Build

1. 데이터베이스 변경 후 make export-content 실행
2. cmd/export-content가 SQLite에서 최신 데이터를 조회
3. refer_landing_page/content/*.ts 파일들을 타입 안전한 TypeScript 상수로 덮어쓰기 생성
4. Next.js 빌드(npm run build)를 통해 15개 정적 HTML 페이지가 100% SSG로 생성

5.3 Live REST API Serving

1. make run 또는 ./bin/api 실행 (기본 포트 :8080)
2. 클라이언트가 /api/v1/* 엔드포인트로 HTTP GET 요청
3. Gin 라우터가 요청을 파싱하고 적절한 도메인 핸들러로 전달
4. 리포지토리 계층이 파라미터화된 SQL 쿼리로 SQLite 조회 후 일관된 JSON Envelope 형식으로 반환