Skip to content
BranchesTags

Repository files navigation

Flutter AI Chatbot (100% Free)

Flutter 개발을 배우는 학생들을 위한 AI 기반 학습 플랫폼입니다. RAG (Retrieval-Augmented Generation) 기술로 Flutter 공식 문서를 학습하고 질문에 답변합니다.

Monthly Cost: $0 (완전 무료)

Live Demo

Tech Stack

┌─────────────────────────────────────────────────────────┐
│              Frontend (Firebase Hosting)                │
│         React 19 + Vite + Firebase Auth                 │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Backend API (Vercel)                       │
│  ┌─────────────────────────────────────────────────┐    │
│  │  Express.js API Server                          │    │
│  │     - /api/chat (RAG Pipeline)                  │    │
│  │     - /api/health (Status)                      │    │
│  └─────────────────────────────────────────────────┘    │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
┌───────────────────┐   ┌───────────────────┐
│  Supabase         │   │  Groq / Gemini    │
│  (pgvector)       │   │  (LLM)            │
│  - 3,768 docs     │   │  - LLaMA 3.3 70B  │
│  - Vector Search  │   │  - Gemini fallback│
└───────────────────┘   └───────────────────┘
Category Technology Cost
Frontend React 19 + Vite $0
Hosting Firebase Hosting $0
Backend Vercel Serverless $0
Vector DB Supabase pgvector $0
LLM Groq (Llama 3.3 70B) $0
Embeddings Hugging Face BAAI/bge-base-en-v1.5 $0
Auth Firebase Auth $0
Chat Storage Firestore $0

Project Structure

Flutter_Chatbot/
├── frontend/                 # React 웹 앱
│   ├── src/
│   │   ├── components/       # React 컴포넌트
│   │   ├── firebase/         # Firebase 설정
│   │   └── i18n/             # 다국어 지원
│   └── .env                  # 환경변수
│
├── supabase-backend/         # Vercel API 서버
│   ├── index.js              # Express API
│   ├── sync-docs.js          # 증분 문서 동기화
│   ├── init-hashes.js        # SHA 해시 초기화
│   ├── setup.sql             # pgvector 설정
│   └── security-fix.sql      # RLS 보안 강화
│
├── .github/workflows/        # GitHub Actions
│   └── sync-docs.yml         # 주간 자동 동기화
│
└── _archived/                # 이전 버전 코드

Features

  • AI Chatbot: Flutter 공식 문서 기반 질의응답
  • RAG System: 3,768개 문서 청크로 학습된 벡터 검색
  • Multi-language: 한국어/영어 자동 전환
  • 30 Flutter Tips: 랜덤 학습 팁 제공
  • Firebase Auth: Google 로그인 지원
  • Chat History: 대화 기록 자동 저장

Setup

1. Supabase 설정

  1. Supabase 프로젝트 생성
  2. SQL Editor에서 setup.sql 실행
  3. SQL Editor에서 security-fix.sql 실행

2. Vercel 배포

cd supabase-backend
npm install
vercel login
vercel --prod

환경변수 설정:

  • SUPABASE_URL
  • SUPABASE_SERVICE_KEY
  • GEMINI_API_KEY (Gemini LLM fallback용)
  • GROQ_API_KEY
  • HF_API_KEY (문서 동기화 임베딩용)

3. 문서 동기화

# 최초 동기화
npm run sync -- --full

# SHA 해시 등록 (증분 동기화 준비)
npm run init-hashes

# 이후 증분 동기화
npm run sync

4. Frontend 배포 (자동화)

frontend/ 디렉토리 내의 코드를 main 브랜치에 Push하면 GitHub Actions를 통해 Firebase Hosting으로 자동 배포됩니다.

GitHub Secrets 필요:

  • FIREBASE_SERVICE_ACCOUNT_HI_PROJECT_FLUTTER_CHATBOT
  • VITE_FIREBASE_API_KEY
  • VITE_FIREBASE_AUTH_DOMAIN
  • VITE_FIREBASE_PROJECT_ID
  • VITE_FIREBASE_STORAGE_BUCKET
  • VITE_FIREBASE_MESSAGING_SENDER_ID
  • VITE_FIREBASE_APP_ID
  • VITE_API_BASE_URL (Vercel 백엔드 API URL)

API Endpoints

Chat API

POST /api/chat
{
  "question": "What is Flutter?",
  "language": "ko"
}

Response:
{
  "success": true,
  "answer": "Flutter는 Google이 개발한...",
  "sources": [...],
  "confidence": 0.89
}

Health Check

GET /api/health

Response:
{
  "status": "ok",
  "service": "Flutter Chatbot Supabase"
}

Auto Sync (GitHub Actions)

매주 월/목 오전 9시(KST) 자동으로 Flutter 문서를 증분 동기화합니다. 수동 실행 시 "전체 재동기화" 옵션 체크 가능 (모델 변경 후 등).

GitHub Secrets 필요:

  • SUPABASE_URL
  • SUPABASE_SERVICE_KEY
  • HF_API_KEY (Hugging Face - 임베딩 생성)

프로젝트 업데이트 절차

코드 변경 후 프로젝트를 업데이트하는 절차는 변경된 부분에 따라 다릅니다.

1. 프론트엔드 (React 앱) 업데이트

프론트엔드 코드를 수정한 경우 main 브랜치에 Push하면 GitHub Actions를 통해 Firebase Hosting으로 자동 배포됩니다. (자세한 내용은 "4. Frontend 배포 (자동화)" 섹션 참조)

2. 백엔드 API (supabase-backend) 업데이트

백엔드 API 코드를 수정한 경우:

cd supabase-backend
npm install # 의존성 변경이 있는 경우
# Vercel은 Git 연동 시 자동으로 배포되므로, 변경사항을 Git에 Push하는 것만으로 충분합니다.
# 수동 배포가 필요한 경우
vercel --prod # Vercel에 배포

3. 문서 동기화 스크립트 (sync-docs.js) 업데이트

supabase-backend/sync-docs.js 파일 자체를 수정한 경우:

  1. 수정된 코드를 Git에 Push합니다.
  2. supabase-backend의 Vercel 배포가 자동으로 업데이트됩니다.
  3. 필요한 경우 GitHub Actions의 "Actions" 탭에서 "Sync Flutter Docs to Supabase" 워크플로우를 수동으로 트리거하여 즉시 동기화를 실행할 수 있습니다. (주간 스케줄에 따라 자동 실행됩니다.)
# 수동 트리거 (GitHub Actions 'Run workflow' 버튼)

4. 전체 프로젝트 업데이트 (모든 구성요소 변경 시)

여러 구성요소(프론트엔드, 백엔드, 동기화 스크립트 등)에 변경 사항이 있는 경우, 일반적으로 다음 순서로 업데이트하는 것을 권장합니다.

  1. 백엔드 API 업데이트: supabase-backend 변경사항을 Git에 Push하고 Vercel 배포가 완료될 때까지 기다립니다.
  2. 문서 동기화 스크립트 업데이트: sync-docs.js 변경사항을 Git에 Push하고 Vercel 배포가 완료될 때까지 기다립니다. (백엔드 API에 포함되므로 2단계와 동일할 수 있음)
  3. 프론트엔드 업데이트: frontend 변경사항을 빌드하고 Firebase Hosting에 배포합니다.
  4. 필요한 경우 문서 재동기화: GitHub Actions에서 Sync Flutter Docs to Supabase 워크플로우를 수동으로 실행하거나 다음 스케줄을 기다립니다.

계정 이전 체크리스트

새 계정/환경으로 프로젝트를 이전할 때 필요한 작업 목록입니다.

1. Firebase 새 프로젝트 생성

  1. Firebase Console → 새 프로젝트 생성
  2. Authentication → Sign-in method → Google 활성화
  3. Firestore Database → 데이터베이스 생성 (production mode)
  4. Hosting → 시작하기
  5. Project Settings → 웹 앱 추가 → 아래 config 값 복사:
    • apiKey, authDomain, projectId, storageBucket, messagingSenderId, appId
  6. firestore.rules 및 firestore.indexes.json 배포: 
    firebase deploy --only firestore

2. Supabase 새 프로젝트 생성

  1. Supabase → 새 프로젝트 생성
  2. Project Settings → API → URL과 service_role key 복사
  3. SQL Editor에서 supabase-backend/setup.sql 실행
  4. SQL Editor에서 supabase-backend/security-fix.sql 실행
  5. 문서 초기 동기화 실행 (아래 "3. 문서 동기화" 참조)

3. API 키 발급

키 발급처 용도
HF_API_KEY Hugging Face 문서 임베딩 생성 (동기화용)
GEMINI_API_KEY Google AI Studio LLM fallback (Groq 실패 시)
GROQ_API_KEY Groq Console 기본 LLM (Llama 3.3 70B)

임베딩 모델: BAAI/bge-base-en-v1.5 (768차원, 무료, RPD 제한 없음) Gemini API: Groq 실패 시 자동 fallback. GEMINI_API_KEY 환경변수만 넣으면 즉시 작동.

4. Vercel 재배포 (백엔드)

cd supabase-backend
vercel login   # 새 계정으로 로그인
vercel --prod

Vercel 대시보드 → 프로젝트 → Settings → Environment Variables에 아래 추가:

  • SUPABASE_URL
  • SUPABASE_SERVICE_KEY
  • GEMINI_API_KEY (LLM fallback)
  • GROQ_API_KEY

5. GitHub Secrets 설정

Repository → Settings → Secrets and variables → Actions에 아래 추가:

Firebase 배포용:

  • FIREBASE_SERVICE_ACCOUNT_HI_PROJECT_FLUTTER_CHATBOT (Firebase 서비스 계정 JSON)
  • VITE_FIREBASE_API_KEY
  • VITE_FIREBASE_AUTH_DOMAIN
  • VITE_FIREBASE_PROJECT_ID
  • VITE_FIREBASE_STORAGE_BUCKET
  • VITE_FIREBASE_MESSAGING_SENDER_ID
  • VITE_FIREBASE_APP_ID
  • VITE_API_BASE_URL (Vercel 백엔드 URL, 예: https://xxx.vercel.app)

문서 자동 동기화용:

  • SUPABASE_URL
  • SUPABASE_SERVICE_KEY
  • HF_API_KEY

6. 로컬 개발 환경 설정

frontend/.env 파일:

VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=...
VITE_FIREBASE_PROJECT_ID=...
VITE_FIREBASE_STORAGE_BUCKET=...
VITE_FIREBASE_MESSAGING_SENDER_ID=...
VITE_FIREBASE_APP_ID=...
VITE_API_BASE_URL=https://xxx.vercel.app

supabase-backend/.env 파일 (로컬 테스트용):

SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_KEY=eyJ...
GEMINI_API_KEY=AIza...
GROQ_API_KEY=gsk_...

7. 문서 초기 동기화

cd supabase-backend
npm install

# 전체 동기화 (최초 1회, 약 3,700개 문서)
SUPABASE_URL=xxx SUPABASE_SERVICE_KEY=xxx GEMINI_API_KEY=xxx node sync-docs.js --full

# 해시 초기화 (이후 증분 동기화 준비)
SUPABASE_URL=xxx SUPABASE_SERVICE_KEY=xxx node init-hashes.js

License

MIT License

Made with love for Flutter learners

About

Flutter 학습자를 위한 RAG 기반 AI 문서 질의응답 플랫폼

flutter-chatbot.vercel.app

Topics

ai-chatbotflutterportfolioragreactsupabase

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages