# Nexus Agent Frontend

> AI와 실무를 연결하는 Nexus Agent 플랫폼의 프론트엔드.

Next.js 16 (App Router) + React 19 + TypeScript 기반. 실시간 AI 채팅(SSE 스트리밍), MCP 서버 관리, Agent Skills, Custom Pages, Workspace 파일 탐색기, 장기 기억(Memory Bank) 관리, 세션 히스토리, 플랫폼 브랜딩/프로필 커스터마이징, 테마/LLM 설정 대시보드를 제공합니다.

## 실행

```bash
pnpm install
pnpm dev        # 개발 서버 (http://localhost:3000)
pnpm build      # 프로덕션 빌드 (static export → out/)
pnpm lint       # ESLint
```

## 구조

```
frontend/
├── package.json                   # 의존성 정의
├── pnpm-lock.yaml                 # pnpm 락 파일
├── pnpm-workspace.yaml            # pnpm 워크스페이스 설정
├── next.config.ts                 # Next.js 설정 (static export)
├── tsconfig.json                  # TypeScript 설정 (@/* path alias)
├── components.json                # shadcn/ui 설정 (new-york 스타일)
├── eslint.config.mjs              # ESLint 설정
├── postcss.config.mjs             # PostCSS 설정 (Tailwind CSS)
├── .env.example                   # 환경 변수 템플릿
├── .gitignore
├── public/                        # 정적 파일
└── src/
    ├── app/
    │   ├── globals.css                # 글로벌 스타일 (oklch 테마 변수)
    │   ├── layout.tsx                 # 루트 레이아웃 (Sidebar, 배경 효과, ThemeProvider)
    │   ├── page.tsx                   # 홈 — ChatInterface
    │   ├── tools/page.tsx             # MCP Servers 대시보드
    │   ├── skills/page.tsx            # Agent Skills 대시보드
    │   ├── pages/page.tsx             # Custom Pages 폴더 브라우저
    │   ├── pages/viewer/page.tsx      # 페이지 뷰어 (HTML / iframe)
    │   ├── workspace/page.tsx         # Workspace 대시보드 (등록/활성화/삭제)
    │   ├── workspace/viewer/page.tsx  # Workspace 뷰어 (파일 트리 + 파일/이미지/미디어 뷰어)
    │   └── settings/page.tsx          # 테마, LLM, 프로필, 플랫폼 브랜딩, 봇 프로필, 메모리, 헬스체크 설정
    ├── components/
    │   ├── chat/
    │   │   ├── ChatInterface.tsx      # 채팅 UI (SSE 스트리밍, 메시지, 파일 첨부, 배경 편집, 활성 워크스페이스 표시)
    │   │   ├── ThinkingBlock.tsx      # 접이식 사고 과정 표시 (도구 호출/결과 실시간 렌더링)
    │   │   ├── FilePreviewChips.tsx   # 첨부 파일 미리보기 칩
    │   │   ├── MCPToolsPanel.tsx      # MCP 도구 사이드 패널
    │   │   ├── SessionPanel.tsx       # 세션 히스토리 패널
    │   │   └── MemoryPanel.tsx        # 장기 기억 관리 패널 (CRUD, 핀 고정, 카테고리 분류)
    │   ├── mcp/
    │   │   ├── MCPServerRow.tsx       # MCP 서버 컴팩트 행 (HoverCard 상세)
    │   │   ├── MCPServerCard.tsx      # MCP 서버 카드
    │   │   ├── AddServerDialog.tsx    # MCP 서버 추가 다이얼로그
    │   │   └── EditServerDialog.tsx   # MCP 서버 수정 다이얼로그
    │   ├── skills/
    │   │   ├── SkillRow.tsx           # 스킬 컴팩트 행 (HoverCard 상세)
    │   │   ├── SkillCard.tsx          # 스킬 카드
    │   │   └── AddSkillDialog.tsx     # 스킬 추가 다이얼로그 (생성/ZIP/임포트)
    │   ├── pages/
    │   │   ├── PageRow.tsx            # 페이지/폴더 컴팩트 행 (인라인 이름변경)
    │   │   ├── PageCard.tsx           # 페이지 카드
    │   │   └── AddPageDialog.tsx      # 페이지 추가 다이얼로그 (업로드/임포트/북마크/폴더)
    │   ├── workspace/
    │   │   ├── WorkspaceRow.tsx       # 워크스페이스 컴팩트 행 (상태 도트, HoverCard 상세)
    │   │   ├── AddWorkspaceDialog.tsx # 워크스페이스 등록 다이얼로그
    │   │   ├── FileTree.tsx           # 재귀 파일 트리 (lazy-loading 폴더 확장)
    │   │   ├── FileViewer.tsx         # 읽기 전용 파일 뷰어 (라인 번호 표시)
    │   │   ├── ImageViewer.tsx        # 이미지 파일 뷰어
    │   │   ├── MediaViewer.tsx        # 오디오/비디오 미디어 뷰어
    │   │   └── BinaryViewer.tsx       # 바이너리 파일 정보 뷰어
    │   ├── providers/
    │   │   ├── ThemeProvider.tsx      # oklch 테마 변수 적용
    │   │   └── BackgroundBlobs.tsx    # 글래스모피즘 배경 효과
    │   ├── layout/
    │   │   └── Sidebar.tsx            # 반응형 사이드바 네비게이션 (동적 브랜딩)
    │   └── ui/                        # shadcn/ui 컴포넌트 (14개)
    │       ├── badge.tsx, button.tsx, card.tsx, dialog.tsx
    │       ├── form.tsx, hover-card.tsx, input.tsx, label.tsx
    │       ├── scroll-area.tsx, select.tsx, sheet.tsx
    │       ├── switch.tsx, tabs.tsx, textarea.tsx
    └── lib/
        ├── config.ts                  # API_BASE_URL 중앙 설정
        ├── utils.ts                   # cn() 헬퍼 (clsx + tailwind-merge)
        ├── file-utils.ts              # 파일 검증 및 base64 변환
        ├── workspace-file-types.ts    # 워크스페이스 파일 타입 분류 유틸리티
        ├── api/
        │   ├── mcp.ts                 # MCP 서버/도구 API 클라이언트
        │   ├── skills.ts              # Skills API 클라이언트
        │   ├── pages.ts               # Pages/폴더/북마크 API 클라이언트
        │   ├── sessions.ts            # 세션 히스토리 API 클라이언트
        │   ├── settings.ts            # LLM 설정/헬스체크 API 클라이언트
        │   ├── workspace.ts           # Workspace CRUD + 파일 트리/내용 API 클라이언트
        │   └── memory.ts              # 메모리 CRUD + 핀 토글 + 설정 API 클라이언트
        └── stores/
            ├── theme.ts               # 테마 상태 (localStorage, oklch 프리셋)
            ├── session.ts             # 세션 상태 관리
            └── profile.ts             # 사용자/봇 프로필 + 플랫폼 브랜딩 상태 (localStorage)
```

## 페이지

| 경로 | 설명 |
|------|------|
| `/` | AI 채팅 — SSE 실시간 스트리밍, 사고 과정 표시, 메시지 송수신, 이미지 첨부, MCP 도구 패널, 세션 패널, Memory Bank 패널, 활성 워크스페이스 배지, 배경 이미지 편집 |
| `/tools` | MCP Servers — 서버 등록/연결/토글, 도구 목록 조회 |
| `/skills` | Agent Skills — 스킬 생성/ZIP 업로드/경로 임포트, SKILL.md 상세 보기 |
| `/pages` | Custom Pages — 폴더 트리 네비게이션, HTML 업로드, URL 북마크, 인라인 이름변경 |
| `/pages/viewer` | 페이지 뷰어 — HTML 콘텐츠 표시 또는 iframe으로 URL 렌더링 |
| `/workspace` | Workspace — 로컬 디렉토리 등록/활성화/삭제 |
| `/workspace/viewer` | Workspace 뷰어 — 2패널 레이아웃 (파일 트리 + 파일/이미지/미디어 뷰어) |
| `/settings` | 설정 — 테마/배경/LLM/프로필/플랫폼 브랜딩/봇 프로필/메모리/연결 상태 |

### Memory Bank 기능

Memory Bank 패널에서 장기 기억을 관리합니다:

- **자동 추출**: 대화 중 LLM이 핵심 사실, 선호도, 패턴, 맥락을 자동 인식하여 저장
- **수동 관리**: 메모리 추가/편집/삭제, 카테고리(preference, context, pattern, fact) 분류
- **핀 고정**: 중요한 메모리에 핀을 걸어 자동 삭제/압축에서 보호 (핀 아이콘 토글)
- **용량 관리**: 사용량 표시, 가득 참/거의 참 경고, 자동 압축/교체 안내

### Workspace 뷰어 레이아웃

```
┌──────────────────────────────────────────────┐
│ [← Back]  workspace-name  [Set as Active]    │
├────────────────┬─────────────────────────────┤
│ File Tree      │ File Viewer                 │
│ (w-80, border) │ (flex-1)                    │
│                │                             │
│ 📁 src/        │  1│ import json             │
│   📄 main.py   │  2│ from typing import...   │
│   📄 utils.py  │  3│                         │
│ 📁 tests/      │  4│ def main():             │
│ 📄 README.md   │  5│     print("hello")      │
│                │                             │
└────────────────┴─────────────────────────────┘
```

- 좌측: FileTree — 폴더 클릭 시 API 호출로 하위 트리 lazy-load, 파일 클릭 시 우측에 표시
- 우측: FileViewer — 텍스트 파일은 라인 번호 + monospace 폰트, 이미지/미디어/바이너리 파일은 전용 뷰어
- 활성 워크스페이스 설정 시 채팅 화면에서 AI가 워크스페이스 도구 사용 가능

## 백엔드 연결

백엔드 API 주소는 `src/lib/config.ts`에서 중앙 관리됩니다.

- **기본값**: `http://localhost:8000` (설정 없이 동작)
- **변경 시**: `frontend/.env.local` 파일을 생성

```bash
# frontend/.env.local (필요할 때만 생성)
NEXT_PUBLIC_API_URL=http://192.168.0.100:8000
```

| 파일 | 역할 |
|------|------|
| `.env.example` | 환경 변수 템플릿 (git에 커밋됨) |
| `.env.local` | 실제 설정 (git에서 제외, 필요할 때만 생성) |

## 디자인 시스템

- **테마**: 다크/라이트 글래스모피즘 (backdrop-blur, 반투명 보더)
- **색상**: oklch 색공간, 6종 액센트 컬러 (amber, blue, emerald, violet, rose, cyan)
- **배경 톤**: 다크 4종 (default, midnight, charcoal, slate) / 라이트 3종 (default, warm, cool)
- **채팅 배경**: 커스텀 이미지 + 배율/위치/투명도 조정 (Settings 및 채팅 화면 내 드래그 편집)
- **컴포넌트**: shadcn/ui (new-york 스타일, Lucide 아이콘, HoverCard 활용)
- **Path alias**: `@/*` → `./src/*`
- **UI 패턴**: 컴팩트 Row 리스트 (호버 시 상세 HoverCard, 호버 시 액션 버튼 표시)
