Neatly — AI 이메일 · 문서 정리 비서

AI 기반 문서 관리 플랫폼. 문서 업로드, Gmail 연동, AI 요약·브리핑, 실시간 채팅을 하나의 서비스에서 제공합니다.

시연 영상

https://github.com/user-attachments/assets/dd162714-f86d-4e3a-a5b9-10f5ddbdd893

서비스: https://neatly-wheat.vercel.app

백엔드는 Render 무료 플랜이라 처음 접속 시 서버가 깨어나는 데 최대 1분 정도 걸립니다.

---

주요 기능

문서 관리

• PDF, DOCX, TXT 파일 업로드 및 텍스트 추출
• 업로드 즉시 LLM 기반 AI 자동 요약 생성
• 폴더·태그로 문서 분류, 드래그 앤 드롭으로 이동
• 전문 검색 (제목·본문·태그)
• 휴지통 — 30일 후 자동 영구 삭제

Gmail 연동

• Google OAuth 2.0 인증으로 Gmail 계정 연결
• 이메일을 문서로 변환 + AI 요약 자동 생성
• 실시간 수신: Gmail Pub/Sub 푸시로 새 메일이 오면 바로 문서화 · 브리핑 (서버가 깨어 있을 땐 2분마다 보조 동기화)
• Premium 플랜: 발신자 필터·스팸 관리
• Gmail 휴지통 이동 / 받은편지함 복원

메일 일정 자동 추출

• 동기화된 메일에서 AI가 마감일 있는 업무 요청을 찾아 일정으로 제안
• 바로 넣지 않고 확인 모달로 물어봄 — 제목·날짜·시간을 고쳐서 추가하거나 무시
• 자동 발송 메일(noreply·뉴스레터·프로모션)은 코드에서 먼저 걸러 AI 판단에서 제외
• 캘린더 일정 시작 전 브라우저 알림

AI 기능

• 문서 요약: 업로드 시 LLM(gpt-oss)으로 3~4문장 요약
• 문서 Q&A: 문서 본문을 컨텍스트로 자연어 질의응답 (Standard 이상)
• AI 일간 브리핑: 오늘 추가된 문서 전체를 분석해 핵심 요약 + 할 일 추천 (Premium)
• 폴더 브리핑: 특정 폴더의 문서를 선택해 즉시 브리핑 생성

실시간 채팅

• WebSocket 기반 그룹 채팅 + 1:1 DM
• 온라인 상태 표시, 읽음 확인, 안읽은 메시지 뱃지
• 이미지 전송, 브라우저 푸시 알림

그 외

• 문서 작성 통계 인사이트 (일별·월별 차트)
• FREE / STANDARD / PREMIUM 플랜 시스템
• 친구 추가·숨김·차단 관리

---

유사 서비스 비교

기능	Neatly	Notion	Evernote	Google Drive
문서 관리·폴더·태그	O	O	O	O
파일 업로드 (PDF·DOCX)	O	O	O	O
AI 자동 요약	O	유료	X	X
AI 문서 Q&A	O	유료	X	X
AI 일간 브리핑	O	X	X	X
Gmail 연동 및 이메일 자동 문서화	O	X	X	X
이메일 자동 동기화	O	X	X	X
실시간 채팅	O	X	X	X

Gmail 이메일을 자동으로 문서로 변환하고 AI가 요약·브리핑까지 생성하는 점이 기존 서비스와의 핵심 차별점입니다.

---

기술 스택

구분	사용 기술
Frontend	React 18, TypeScript, Vite, React Router v6
Backend	FastAPI, SQLAlchemy, PostgreSQL (Supabase)
AI	Groq API (gpt-oss-120b / gpt-oss-20b) · 장애·한도 초과 시 Cerebras 자동 전환
인증	JWT, Google OAuth 2.0
실시간	WebSocket
스케줄러	APScheduler (보조 동기화 · 매일 04:00 Gmail 감시 갱신) · GitHub Actions (매일 03:53 서버 깨우기)
배포	Vercel (Frontend) · Render (Backend) · Supabase (DB)
파일 파싱	pdfplumber, python-docx

---

아키텍처

my-app/                  # React 프론트엔드 (Vite)
  src/
    pages/               # 각 페이지 컴포넌트
    components/          # 공통 컴포넌트 (Sidebar, Layout, ChatModal 등)
    api/                 # Axios 기반 API 클라이언트
    context/             # Toast, Refresh 전역 상태

backend/                 # FastAPI 백엔드
  routers/
    auth.py              # 로그인·회원가입·JWT
    documents.py         # 문서 CRUD + AI 요약
    gmail.py             # Gmail API 연동
    gmail_push.py        # Gmail Pub/Sub 실시간 수신 (watch 등록 · 푸시 처리)
    calendar.py          # 메일에서 추출한 일정
    email_sync.py        # 이메일 자동 동기화
    briefing.py          # AI 브리핑 생성
    ai.py                # 문서 Q&A
    chat.py              # WebSocket 채팅
    search.py            # 전문 검색
    friends.py           # 친구 관계
  scheduler.py           # 주기적 백그라운드 작업
  models.py              # DB 스키마 (SQLAlchemy)
  gmail_utils.py         # Gmail 자격증명 공통 유틸

.github/workflows/daily-wake.yml   # 매일 03:53 KST 서버를 깨워 04:00 Gmail 감시 갱신이 돌게 함

---

실행 방법

사전 준비

• Python 3.11+
• Node.js 18+
• PostgreSQL 14+ (또는 Supabase 무료 프로젝트)
• Groq API 키
• Google Cloud OAuth 2.0 자격증명 (Gmail API 활성화 필요)

백엔드

cd backend
pip install -r requirements.txt

.env 파일 생성:

DATABASE_URL=postgresql://user:password@localhost:5432/neatly
SECRET_KEY=your-secret-key
GROQ_API_KEY=your-groq-api-key
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/gmail/callback
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:8000

python create_tables.py   # DB 테이블 생성
uvicorn main:app --reload

프론트엔드

cd my-app
npm install

.env 파일 생성:

VITE_API_BASE_URL=http://localhost:8000

npm run dev

---

플랜별 기능

기능	FREE	STANDARD	PREMIUM
문서 업로드 (하루 3개)	O	O	O
문서 업로드 (무제한)		O	O
AI 문서 Q&A		O	O
Gmail 연동·변환		O	O
AI 일간 브리핑			O
Gmail 자동 동기화			O
발신자 필터			O

---

API 문서

서버 실행 후 http://localhost:8000/docs 에서 Swagger UI로 확인할 수 있습니다.

---

트러블슈팅

문제	원인	해결
Google OAuth "Missing code verifier" 오류	최신 google-auth-oauthlib이 PKCE를 자동 추가하는데, 서버사이드 리다이렉트 흐름에서 code_verifier를 요청 사이에 유지할 수 없음	google-auth-oauthlib 대신 requests_oauthlib.OAuth2Session을 직접 사용해 PKCE 없이 인가 코드 흐름 처리
Gmail 연결 후 1시간이 지나면 동기화가 silently 실패	OAuth 콜백에서 expires_at을 DB에 저장하지 않아 creds.expiry = None → creds.expired 가 항상 False → 토큰 갱신 건너뜀 → Gmail API 401 → except 절이 0 반환	콜백에서 token["expires_at"]을 gmail_token_expiry에 저장, refresh_if_expired()에 expiry is None 조건 추가
LLaMA 출력에 베트남어 자모·박스 문자 혼입	Groq API가 간헐적으로 비정상 유니코드 출력	_sanitize_ai_output() 후처리 함수 추가 — unicodedata.category()로 제어문자 필터링, 허용 문자셋 정규식 적용
iOS Safari에서 앱 전체 흰 화면	window.Notification 미지원 환경에서 Notification API 접근 시 런타임 오류	typeof Notification !== 'undefined' 가드 추가, 최상단 ErrorBoundary로 치명적 오류 catch
WebSocket 재연결 시 메시지 중복 수신	네트워크 끊김 후 재연결 시 같은 사용자의 연결이 두 개 이상 유지됨	ConnectionManager.connect()에서 동일 user_id의 기존 연결을 close() 후 교체
문서 목록 API에서 N+1 쿼리 발생	문서마다 태그 SELECT가 개별 실행 (문서 100개 = 쿼리 101회)	docs_with_tags_batch()로 전체 문서 ID를 IN 쿼리 1회로 태그 일괄 조회 후 메모리 매핑 (쿼리 수 N+1 → 2)
MySQL → PostgreSQL 마이그레이션 충돌	CHAR(36) 타입 비교 불일치, Enum 타입명 미지정으로 PostgreSQL 충돌	String(36)으로 교체, Enum 선언에 name= 파라미터 명시
Vercel 배포 후 직접 URL 접근 시 404	SPA 라우팅 미설정	vercel.json에 모든 경로를 index.html로 rewrite 설정 추가
일주일 동안 메일이 없으면 실시간 수신이 끊김	Gmail 감시(watch)는 7일 뒤 만료되고 갱신은 서버가 깨어 있을 때만 실행 · Render 무료 서버는 요청이 없으면 잠듦	GitHub Actions가 매일 03:53에 서버를 깨워 10분간 유지 → 04:00 갱신 작업이 매일 실행