doublesilver · doublesilver · Feb 27, 2026 · Feb 27, 2026 · Feb 27, 2026
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
@@ -74,7 +74,7 @@ jobs:
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
           vercel link \
-            --project knowledge-copilot \
+            --project app \
             --scope "$VERCEL_SCOPE" \
             --confirm \
             --token "$VERCEL_TOKEN"
@@ -150,7 +150,7 @@ jobs:
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
           vercel link \
-            --project knowledge-copilot \
+            --project app \
             --scope "$VERCEL_SCOPE" \
             --confirm \
             --token "$VERCEL_TOKEN"

diff --git a/README.md b/README.md
@@ -1,90 +1,258 @@
-# Knowledge Copilot
+# Knowledge Copilot - AI Document Copilot
 
-이 프로젝트는 포트폴리오 목적의 **AI 문서 기반 지식 코파일럿**입니다.
-- 문서 업로드 (텍스트)
-- RAG 기반 검색 + 질의
-- 근거(citation) 표시
-- 액션형 기능 (문서 요약)
-- 피드백/메트릭 집계
+> **한 문서에서 근거 기반으로 답하는 팀형 지식 동반자**
+>
+> 업로드한 문서를 임베딩하고, 검색 기반 질의와 액션 API를 제공하는 풀스택 AI 포트폴리오 프로젝트입니다.
 
-## 폴더 구성
-- `api/`: FastAPI 백엔드
-- `app/`: Next.js 프론트엔드
-- `docs/`: 설계/로드맵 메모
-- `docker-compose.yml`: 통합 실행 환경
+<div align="center">
 
-## 빠른 시작
+[![Deploy Status](https://img.shields.io/badge/deploy-GitHub_Actions-2088FF?style=for-the-badge&logo=github-actions&logoColor=white)](https://github.com/doublesilver/knowledge-copilot/actions)
+[![CI/CD](https://img.shields.io/badge/CI%2FCD-dev%20%26%20prod-4CAF50?style=for-the-badge)](https://github.com/doublesilver/knowledge-copilot/actions/workflows/ci-cd.yml)
+[![Vercel](https://img.shields.io/badge/Vercel-Frontend-black?style=for-the-badge&logo=vercel)](https://vercel.com)
+[![Railway](https://img.shields.io/badge/Railway-API-0B0D0E?style=for-the-badge&logo=railway)](https://railway.app)
 
-1. Python 의존성 설치
-```bash
-cd /mnt/c/Users/korea/project3/api
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
-pip install -r requirements.txt
+</div>
+
+---
+
+## 프로젝트 개요
+
+| 항목 | 내용 |
+|------|------|
+| **프로젝트명** | Knowledge Copilot |
+| **유형** | AI 문서 질의/요약 MVP (포트폴리오) |
+| **개발 기간** | 2026-02-27 기준 구축 단계 |
+| **개발 인원** | 1인 풀스택 |
+| **현재 버전** | v0.1.0 |
+| **서비스 URL** | 배포 URL 별도 등록(공개 도메인 미공개) |
+
+---
+
+## 주요 기능
+
+| 기능 | 설명 |
+|------|------|
+| **문서 업로드** | 텍스트/파일 기반 문서를 업로드해 인덱싱 |
+| **RAG 질의** | 문서 기반 근거가 포함된 답변 반환 |
+| **문서 상세 조회** | 업로드한 문서/청크 기반 조회 |
+| **피드백 수집** | 질의 결과 평점 및 메모 저장 |
+| **액션 실행** | 사전 정의된 액션 API 엔드포인트 제공 |
+| **운영 메트릭** | 질의 수, 지연시간, 피드백 지표 조회 |
+| **CI/CD 자동 배포** | `dev`/`main` 브랜치 기준 자동 배포 |
+
+---
+
+## 기술 스택
+
+```mermaid
+flowchart LR
+    subgraph Frontend[Frontend (Vercel)]
+        N[Next.js 14.2.15]
+        React[React 18.3.1]
+        TypeScript[TypeScript 5.5.4]
+    end
+
+    subgraph Backend[Backend (Railway)]
+        FastAPI[FastAPI 0.112.0]
+        PyEnv[Python 3.12]
+        Uvicorn[Uvicorn 0.30.6]
+        SQLite[SQLite (파일 DB)]
+    end
+
+    User[브라우저] --> N --> FastAPI
+    FastAPI --> SQLite
+    FastAPI --> OpenAI[Embedding/Chat API]
+```
+
+### 스택 정리
+
+| 영역 | 사용 기술 |
+|------|----------|
+| Frontend | Next.js, React, TypeScript |
+| Backend | FastAPI, Pydantic, Uvicorn |
+| Storage | SQLite (프로토타입 DB) |
+| AI | OpenAI(임베딩/챗 모델, 옵션) |
+| 배포 | Vercel, Railway, GitHub Actions |
+| 테스트 | pytest |
+
+---
+
+## 아키텍처
+
+```mermaid
+flowchart TD
+    subgraph Browser[Client]
+        UI[Next.js UI]
+    end
+    subgraph API[API Layer]
+        FAST[FastAPI]
+        ROUTES[REST endpoints /api/v1/*]
+        DB[(SQLite)]
+    end
+
+    UI -->|HTTPS| ROUTES
+    ROUTES --> FAST
+    FAST --> DB
+    FAST --> OpenAI[(OpenAI API)]
+```
+
+### API 엔드포인트
+
+| 메서드 | 경로 | 용도 |
+|--------|------|------|
+| GET | `/api/v1/health` | 헬스체크 |
+| POST | `/api/v1/documents` | 문서 업로드 |
+| GET | `/api/v1/documents` | 문서 목록 |
+| GET | `/api/v1/documents/{id}` | 문서 상세 |
+| POST | `/api/v1/queries` | 질의 처리 |
+| GET | `/api/v1/queries/{id}` | 질의 상세 |
+| POST | `/api/v1/evals` | 사용자 피드백 수집 |
+| POST | `/api/v1/agent/actions` | 액션 실행 |
+| GET | `/api/v1/metrics` | 운영 메트릭 |
+
+---
+
+## 프로젝트 구조
+
+```text
+project3/
+├── app/                  # Next.js 프론트엔드
+│   ├── src/
+│   ├── public/
+│   └── package.json
+├── api/                  # FastAPI 백엔드
+│   ├── src/
+│   ├── requirements.txt
+│   ├── Dockerfile
+│   └── pytest
+├── docs/                 # 배포/로드맵 문서
+├── .github/workflows/    # CI/CD
+├── scripts/              # 배포 전 검증 스크립트
+└── .env, .env.example    # 로컬 환경설정
 ```
 
-2. API 실행
+---
+
+## 로컬 실행 방법
+
+### 사전 설치
+
+- Node.js 20+
+- Python 3.12+
+
+### Backend 실행
+
 ```bash
-cp ../.env.example ../.env   # 최초 1회만
+cd api
+cp ../.env.example ../.env  # 최초 1회
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
+pip install -r requirements.txt
 uvicorn src.main:app --reload --env-file ../.env
 ```
 
-3. 프론트 실행
+### Frontend 실행
+
 ```bash
-cd ../app
+cd app
 npm install
 npm run dev
 ```
 
-4. 배포 환경 기준
-- Frontend: Vercel
-- Backend: Railway
+### 통합 실행
 
-> 실제 운영 배포에서는 Vercel/Railway 환경 변수에 `NEXT_PUBLIC_API_BASE`, `OPENAI_API_KEY` 등을 설정합니다.
-
-5. 또는 Docker로 통합 실행
 ```bash
 docker compose up --build
 ```
 
-## 배포 플로우 (Git 기준)
+### 체크리스트
+
+```bash
+cd api
+python -m pytest -q
+
+cd ../app
+npm run build
+```
+
+---
+
+## 배포/운영
+
+### Git 기반 자동 배포 전략
 
-### 브랜치 전략
-- `dev` 또는 `development`: 개발/스테이징 배포 대상
-- `main`: 실운영(Production) 배포 대상
+- **dev / development 브랜치 push**: 개발 환경 배포(Development)
+- **main 브랜치 push**: 실운영 배포(Production)
+- `main` 배포는 운영 정책상 `dev` 검증 흐름 이후 반영
 
-### 배포 규칙
-1. 로컬에서 코드 수정
-2. `git add`, `git commit`, `git push`  
-   - `dev` 브랜치에 push → 자동으로 **개발 배포** 실행
-   - `main` 브랜치에 push → 자동으로 **실운영 배포** 실행
-3. 실운영 배포는 개발 배포가 통과한 커밋만 머지 전제(`main` 머지/리뷰 정책을 이용)
+### 배포 산출물
+
+- Frontend: Vercel (`app` 디렉터리 기준)
+- Backend: Railway (`api` 디렉터리 기준)
+
+### GitHub Actions 필수 Secret
 
-### GitHub Actions 설정 항목
-`Settings > Secrets and variables > Actions`에 아래 값이 있어야 합니다.
 - `VERCEL_TOKEN`
 - `VERCEL_SCOPE`
 - `RAILWAY_TOKEN`
 - `RAILWAY_SERVICE_NAME`
 - `RAILWAY_DEV_ENVIRONMENT`
 
-### Vercel/배포 환경 대응
-- Vercel은 기본적으로 브랜치별 Preview/Production 라우팅을 사용하도록 `.github/workflows/ci-cd.yml`에서 분기 처리
-- Railway는 환경명을 `production` / `development`로 나눠 배포하도록 구성
-- 배포 시점은 GitHub Push 이벤트 기준으로 자동 실행
-
-## API
-- `POST /api/v1/documents`: 문서 업로드
-- `GET /api/v1/documents`: 문서 목록
-- `GET /api/v1/documents/{id}`: 문서 상세
-- `POST /api/v1/queries`: 질문 질의
-- `GET /api/v1/queries/{id}`: 질의 상세
-- `POST /api/v1/evals`: 질의 피드백
-- `POST /api/v1/agent/actions`: 액션 실행
-- `GET /api/v1/metrics`: 메트릭
-- `GET /api/v1/health`: 상태 체크
-
-## 운영 메모
-- OpenAI API 키가 없을 경우 로컬 임베딩(데모 모드) 및 단순 응답 경로로 동작합니다.
-- `CORS_ORIGINS`는 배포 환경에 맞춰 업데이트합니다.
-- 배포 가이드는 [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)를 참고하세요.
+---
+
+## 테스트
+
+현재 기준으로 검증 가능한 항목
+
+- `pytest` (백엔드 단위/API 기본 테스트)
+- `npm run build` (Next.js 빌드 검증)
+- GitHub Actions 체크 자동화
+
+```bash
+cd api
+python -m pytest -q
+
+cd ../app
+npm run build
+```
+
+---
+
+## 개발 타임라인
+
+- v0.1.0: CI/CD 안정화 및 문서화 정리
+- v0.2.0: 질문 정합성 개선, 프롬프트 강화
+- v0.3.0: 인증/권한, 멀티테넌트, 지표 대시보드 고도화
+
+---
+
+## 보안 & 운영 노트
+
+- OpenAI 키/토큰은 `.env` 또는 플랫폼 Secret으로만 관리
+- CORS는 환경별로 제한하여 배포
+- 파일 업로드는 UTF-8 텍스트 기반 처리로 제한
+- SQLite는 포트폴리오/샘플 단계의 저장소로, 운영 요구 시 PostgreSQL 교체 고려
+
+---
+
+## 문서
+
+- [DEPLOYMENT.md](./docs/DEPLOYMENT.md)
+- [ROADMAP.md](./docs/ROADMAP.md)
+- [CI/CD workflow](.github/workflows/ci-cd.yml)
+
+---
+
+## License
+
+MIT License
+
+---
+
+<div align="center">
+
+이 프로젝트는 포트폴리오 제출 및 면접용 실무형 구현 역량 증빙 목적입니다.
+
+**Made for practical AI engineering interview readiness.**
+
+</div>