Skip to content

README.md

Latest commit

 

History

History
322 lines (254 loc) · 14.4 KB

README.md

File metadata and controls

322 lines (254 loc) · 14.4 KB

🇰🇷 개요 (Korean)

Next.js 15(App Router) + React 19 기반의 AI 캐릭터 대화/창작 플랫폼입니다. Firebase(인증/Firestore/Storage/Analytics)와 Supabase(pgvector)를 결합해 장기 기억 RAG, 요약(SUPA/HYPA 롤업), 그룹 채팅, 캐릭터/로어 관리, 포인트·멤버십·결제(Stripe/Patreon) 기능을 제공합니다. PWA와 Vercel Cron도 지원합니다.

주요 폴더와 코드(일부):

  • src/app — 라우트(App Router), api/* 서버 라우트, chat, ranking, lorebook, settings, admin 등 화면
  • src/utils/vector/* — 임베딩/하이브리드 검색/RAG/요약 저장소(Supabase)
  • src/utils/memory/* — 요약 정책/프롬프트/요약기(SUPA/HYPA)
  • src/firebase/* — Firebase 클라이언트/어드민 초기화, 컬렉션 유틸
  • supabase/schema/*.sql — pgvector/tsvector 기반 스키마와 RPC(SQL Editor에서 실행)
  • docs/*.md — 그룹 채팅/출석 등 기능 설계 문서

핵심 기능

  • AI 대화
    • 단일/그룹 채팅, 캐릭터별 프로필/이미지 매칭, 최근 대화 요약 삽입
    • LLM: Google AI Studio(Gemini/Vertex), OpenRouter(Anthropic/OpenAI)
    • 장기 기억(RAG): Supabase pgvector + tsvector 하이브리드 검색, 요약 우선(summary-first) 검색
  • 컨텐츠/자산
    • 캐릭터·로어북 CRUD, 이미지 생성(/api/generate-image) 및 요약(/api/summarize)
  • 경제/랭킹
    • 포인트 잔액/거래, Stripe 결제/웹훅, Patreon 연동
    • 일/주/월 랭킹 집계(cron) + 조회(/api/rankings)
  • 관리/보안
    • 관리자 권한 관리(src/app/admin/users/page.tsx), 삭제/정리용 cron
    • Firestore 규칙/인덱스(firestore.rules, firestore.indexes.json)
  • 배포/운영
    • Vercel Cron(vercel.json), PWA(next-pwa, public/manifest.json, public/sw.js)

기술 스택

  • Web: Next.js 15, React 19, TypeScript, Mantine + MUI
  • Backend(App Router API): Firebase Admin, Supabase(Postgres + pgvector + pg_trgm + tsvector)
  • AI: Google Generative AI/Vertex, OpenRouter, OpenAI(임베딩 포함)
  • Payments: Stripe(Checkout/Webhook), Patreon OAuth
  • Infra: Vercel, PWA, Vercel Cron

빠른 시작

사전 요구사항

  • Node.js 20+ 권장, pnpm 9+ (repo에 pnpm-lock.yaml 존재)
  • Firebase 프로젝트, Supabase 프로젝트, Stripe 계정, (선택) Patreon 클라이언트
  1. 의존성 설치
pnpm install
  1. 환경 변수 준비
  • .env.example를 참고해 .env 또는 .env.local을 채웁니다.
  • 꼭 필요한 값(요약):
    • Firebase Web: NEXT_PUBLIC_FIREBASE_*
    • Firebase Admin: FIREBASE_ADMIN_SDK_CONFIG(JSON), 또는 서비스 계정 파일 지정(GOOGLE_APPLICATION_CREDENTIALS)
    • Supabase(Server-only): SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, (옵션) SUPABASE_ANON_KEY
    • AI 키: GOOGLE_AI_STUDIO_API_KEY 또는 GOOGLE_AI_STUDIO_API_KEYS, (옵션) OPENROUTER_API_KEY, OPENAI_API_KEY
    • 결제: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
    • Cron 보안: CRON_SECRET(랭킹 집계), CRON_SECRET_TOKEN(정리 작업)
    • RAG/메모리: 아래 RAG/Memory 섹션 참조

보안 주의: SUPABASE_SERVICE_ROLE_KEY는 절대 클라이언트에 노출되면 안 됩니다. 서버 전용입니다.

  1. Supabase 스키마 적용
  • Supabase Dashboard → SQL Editor에서 아래 순서대로 실행:
    • supabase/schema/001_chat_message_embeddings.sql
    • supabase/schema/002_match_chat_messages.sql
    • supabase/schema/004_enable_trgm_and_lexical.sql
    • supabase/schema/005_match_chat_messages_hybrid.sql
    • supabase/schema/006_parent_child_windowing.sql
    • supabase/schema/007_memory_summaries.sql
    • supabase/schema/008_memory_summaries_param_fix.sql
    • supabase/schema/009_memory_roomid_to_text.sql
    • supabase/schema/010_memory_summaries_rpc_roomid_text.sql
  1. 개발 서버 실행
pnpm dev

브라우저에서 http://localhost:3000 접속

환경 변수(요약)

Firebase

  • NEXT_PUBLIC_FIREBASE_API_KEY, NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN, NEXT_PUBLIC_FIREBASE_PROJECT_ID, NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET, NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID, NEXT_PUBLIC_FIREBASE_APP_ID, NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID, (옵션) NEXT_PUBLIC_FIREBASE_VAPID_KEY
  • Admin: FIREBASE_ADMIN_SDK_CONFIG(문자열 JSON) 또는 GOOGLE_APPLICATION_CREDENTIALS(파일 경로)

Supabase (서버 전용)

  • SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, (옵션) SUPABASE_ANON_KEY

AI/임베딩

  • Google AI Studio: GOOGLE_AI_STUDIO_API_KEY 또는 GOOGLE_AI_STUDIO_API_KEYS
  • OpenRouter(Anthropic/OpenAI 경유): OPENROUTER_API_KEY
  • OpenAI 임베딩: OPENAI_API_KEY, (옵션) EMBED_PROVIDER=openai|openrouter|local, EMBED_MODEL=text-embedding-3-small, LOCAL_EMBEDDING_URL

결제/멤버십

  • STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
  • PATREON_CLIENT_ID, PATREON_CLIENT_SECRET, PATREON_REDIRECT_URI

Cron/운영

  • CRON_SECRET, CRON_SECRET_TOKEN
  • PWA는 next-pwa 설정(개발 모드 비활성)

요약/메모리/RAG

  • 메모리 정책(src/utils/memory/policy.ts):
    • SUPA_HYPA_MEMORY_ENABLED=true|false (기본 on)
    • MEMORY_RETRIEVAL_MODE=summary_only|cascaded|messages_first (기본 cascaded)
    • SUPA_THRESHOLD_TOKENS, SUPA_WINDOW_MESSAGES, HYPA_ROLLUP_CHUNKS, SUPA_ROLLUP_MAX_GAP_MINUTES, HYPA_ROLLUP_PERIOD_HOURS
    • MEMORY_SUMMARY_K1, MEMORY_SUMMARY_K2, MEMORY_MIN_SCORE, MEMORY_ALPHA, MEMORY_WEIGHT_BETA, DECAY_HALFLIFE_HOURS, MAX_CONTEXT_TOKENS_FOR_MEMORY
  • RAG 검색(src/utils/vector/rag.ts):
    • RAG_MODE=v1|hybrid(기본 v1), RAG_K, RAG_FETCH_K, RAG_MIN_SCORE, RAG_ALPHA, RAG_WINDOW_SIZE, RAG_USE_TSV, RAG_USE_MQ, RAG_USE_HYDE, RAG_USE_RERANK, RAG_DECAY_HALFLIFE_HOURS, DEBUG_RAG
  • 요약 API(src/app/api/summarize/route.ts):
    • SUMMARY_SERVER_MAX_INPUT_CHARS, SUMMARY_SERVER_CHUNK_CHARS, SUMMARY_SERVER_MAX_MESSAGES, (클라이언트 제한) SUMMARY_CLIENT_*

참고: .env.example에 전체 예시가 포함되어 있습니다.

RAG/Memory 개요

  • 인덱싱: /api/vector/index-message → chat_message_embeddings 업서트
  • 검색: 하이브리드(RAG_MODE=hybrid) = pgvector(semantic) + trigram/tsvector(lexical) + 시간감쇠 → match_chat_messages_hybrid
  • 요약 우선(summary-first): chat_memory_summaries(SUPA=level 0, HYPA=level 1)에서 먼저 매칭 → 필요시 메시지 스니펫 보강
  • 자동 롤업:
    • SUPA: 최근 창 크기/토큰 임계 도달 시 runSupaSummarization으로 요약 저장
    • HYPA: 일정 개수/기간 경과 시 runHypaRollup으로 상위 요약 및 링크 저장(chat_memory_links)
  • 통합 시스템 블록: 검색/요약 결과를 시스템 프롬프트로 주입하여 답변 품질 향상

관련 파일

  • src/app/api/chat/bot-response/route.ts — RAG 주입, 요약 롤업, 멀티 모델 지원
  • src/utils/vector/* — 임베딩/검색/압축/시스템블록
  • src/utils/memory/* — 정책/프롬프트/저장소
  • supabase/schema/*.sql — 테이블/인덱스/RPC 정의

주요 API (발췌)

  • 채팅
    • POST /api/chat/bot-response — 캐릭터 응답 생성 + RAG 주입/요약 롤업
    • POST /api/chat/convert — 그룹↔개인 방 전환, 포크 관리
    • POST /api/vector/index-message — 메시지 임베딩 인덱싱
  • 생성/요약
    • POST /api/generate-lore — 로어/첫 메시지 생성(WW+ 형식)
    • POST /api/generate-image — 이미지 생성(선택)
    • POST /api/summarize — 대화 요약
  • 경제/랭킹
    • POST /api/stripe/checkout, POST /api/stripe/webhook — 결제/웹훅
    • GET /api/rankings — 일/주/월 랭킹 조회
    • GET /api/cron/aggregate-rankings/* — Vercel Cron 대상(헤더 X-Cron-Auth: $CRON_SECRET)

배포/운영

  • Vercel 배포 권장. vercel.json에 Cron이 정의되어 있습니다.
  • Stripe Webhook은 STRIPE_WEBHOOK_SECRET 환경변수로 서명 검증을 수행합니다.
  • Vertex/Google AI 사용 시 서비스 계정 자격증명이 필요합니다(GOOGLE_APPLICATION_CREDENTIALS 또는 JSON 문자열).

보안 체크리스트

  • 서비스 롤 키/서비스 계정 JSON은 절대 클라이언트에 노출 금지
  • Firestore Rules/Indexes 동기화(firestore.rules, firestore.indexes.json)
  • Stripe Webhook 서명/비용 추적(포인트 차감 로직)

스크립트

package.json 일부 스크립트:

  • dev, build, start, lint
  • 마이그레이션/정리: scripts/migrations/*, src/scripts/* (예: 빈 채팅방 정리, 기본값 백필 등)

문서

  • 그룹 채팅: docs/group-chat.md
  • 출석 설계: docs/attendance-design.md

라이선스

  • 미정 또는 레포지토리 소유자 정책을 따릅니다.

🇺🇸 Overview (English)

An AI character chat/creation platform built with Next.js 15 (App Router) and React 19. It combines Firebase (Auth/Firestore/Storage/Analytics) and Supabase (pgvector) to deliver long‑term memory RAG, summary rollups (SUPA/HYPA), group chat, character/lore management, and an economy layer (points, Stripe, Patreon). PWA and Vercel Cron are supported.

Highlighted directories:

  • src/app — Routes (App Router), server routes under api/*, pages for chat, ranking, lorebook, settings, admin
  • src/utils/vector/* — Embeddings, hybrid retrieval, RAG, summary repository (Supabase)
  • src/utils/memory/* — Policy/prompts/summarizer (SUPA/HYPA)
  • src/firebase/* — Firebase client/admin setup, collection helpers
  • supabase/schema/*.sql — pgvector/tsvector schema and RPCs (run in SQL Editor)
  • docs/*.md — Feature specs (group chat, attendance)

Features

  • AI Chat
    • Single/group chat, per‑character profiles/image selection, recent summary injection
    • LLM providers: Google AI Studio (Gemini/Vertex), OpenRouter (Anthropic/OpenAI)
    • Long‑term memory (RAG): Supabase pgvector + tsvector hybrid, summary‑first retrieval
  • Content/Assets
    • Character/lorebook CRUD, image generation (/api/generate-image), conversation summarization (/api/summarize)
  • Economy/Ranking
    • Points balance/ledger, Stripe checkout/webhook, Patreon OAuth
    • Daily/weekly/monthly ranking aggregation (cron) and fetch (/api/rankings)
  • Admin/Security
    • Admin role management (src/app/admin/users/page.tsx), cleanup cron
    • Firestore rules and indexes (firestore.rules, firestore.indexes.json)
  • Ops
    • Vercel Cron (vercel.json), PWA (next-pwa, public/manifest.json, public/sw.js)

Stack

  • Web: Next.js 15, React 19, TypeScript, Mantine + MUI
  • Backend: Firebase Admin, Supabase (Postgres + pgvector + pg_trgm + tsvector)
  • AI: Google Generative AI/Vertex, OpenRouter, OpenAI (incl. embeddings)
  • Payments: Stripe (Checkout/Webhook), Patreon
  • Infra: Vercel, PWA, Vercel Cron

Quick Start

Prereqs

  • Node.js 20+ recommended, pnpm 9+
  • Firebase project, Supabase project, Stripe account, (optional) Patreon client
  1. Install deps
pnpm install
  1. Configure env
  • Copy .env.example → .env or .env.local and fill in values.
  • Minimum required:
    • Firebase Web: NEXT_PUBLIC_FIREBASE_*
    • Firebase Admin: FIREBASE_ADMIN_SDK_CONFIG (JSON) or GOOGLE_APPLICATION_CREDENTIALS
    • Supabase (server‑only): SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, (opt) SUPABASE_ANON_KEY
    • AI keys: GOOGLE_AI_STUDIO_API_KEY or GOOGLE_AI_STUDIO_API_KEYS, (opt) OPENROUTER_API_KEY, OPENAI_API_KEY
    • Payments: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
    • Cron: CRON_SECRET (aggregation), CRON_SECRET_TOKEN (cleanup)

Important: Never expose SUPABASE_SERVICE_ROLE_KEY to the client. It’s server‑only.

  1. Apply Supabase schema
  • Run the SQL files in this order via Supabase SQL Editor: 001_chat_message_embeddings.sql → 002_match_chat_messages.sql → 004_enable_trgm_and_lexical.sql → 005_match_chat_messages_hybrid.sql → 006_parent_child_windowing.sql → 007_memory_summaries.sql → 008_memory_summaries_param_fix.sql → 009_memory_roomid_to_text.sql → 010_memory_summaries_rpc_roomid_text.sql
  1. Start dev server
pnpm dev

Open http://localhost:3000

Env Summary

Firebase

  • NEXT_PUBLIC_FIREBASE_* for client config
  • Admin: FIREBASE_ADMIN_SDK_CONFIG (stringified JSON) or GOOGLE_APPLICATION_CREDENTIALS

Supabase (server‑only)

  • SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, (opt) SUPABASE_ANON_KEY

AI/Embeddings

  • Google AI Studio: GOOGLE_AI_STUDIO_API_KEY or GOOGLE_AI_STUDIO_API_KEYS
  • OpenRouter: OPENROUTER_API_KEY
  • OpenAI embeddings: OPENAI_API_KEY, (opt) EMBED_PROVIDER, EMBED_MODEL, LOCAL_EMBEDDING_URL

Payments/Membership

  • STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
  • PATREON_CLIENT_ID, PATREON_CLIENT_SECRET, PATREON_REDIRECT_URI

Cron/Ops

  • CRON_SECRET, CRON_SECRET_TOKEN

Summary/Memory/RAG

  • Memory policy (src/utils/memory/policy.ts): thresholds, modes
  • RAG retrieval (src/utils/vector/rag.ts): mode/hybrid knobs, decay, debug
  • Summarizer API (src/app/api/summarize/route.ts): server/client budget limits

RAG/Memory

  • Indexing via /api/vector/index-message → chat_message_embeddings
  • Retrieval: hybrid (pgvector + lexical with optional decay) via match_chat_messages_hybrid
  • Summary‑first: match in chat_memory_summaries (SUPA/HYPA) and optionally enrich with message snippets
  • Automatic rollups: SUPA and HYPA are produced based on thresholds and linked in chat_memory_links
  • Unified system block injected into model prompts to improve grounding

See:

  • src/app/api/chat/bot-response/route.ts
  • src/utils/vector/*, src/utils/memory/*
  • supabase/schema/*.sql

APIs (selected)

  • Chat: POST /api/chat/bot-response, POST /api/chat/convert, POST /api/vector/index-message
  • Generation/Summarization: POST /api/generate-lore, POST /api/generate-image, POST /api/summarize
  • Economy/Ranking: POST /api/stripe/checkout, POST /api/stripe/webhook, GET /api/rankings
  • Cron: GET /api/cron/aggregate-rankings/* (set X-Cron-Auth: $CRON_SECRET)

Deploy/Ops

  • Prefer Vercel. Cron jobs are defined in vercel.json.
  • Stripe webhook verification uses STRIPE_WEBHOOK_SECRET.
  • Vertex/Google AI requires proper service account credentials (GOOGLE_APPLICATION_CREDENTIALS or JSON string var).

Security

  • Never expose service role keys or service account JSON to the client.
  • Keep Firestore rules and indexes in sync.
  • Monitor token usage and point deduction for paid models.

Scripts

  • Core: dev, build, start, lint
  • Migrations/maintenance under scripts/migrations/*, src/scripts/*

Docs

  • Group chat: docs/group-chat.md
  • Attendance: docs/attendance-design.md

License

  • Apache-2.0 licensed.