NoteFlow Backend

노트/폴더/파일을 중심으로 한 지식 관리 백엔드입니다. OCR(PDF/이미지/문서), 음성(STT), 요약/문제생성 등의 생산성 기능과 소셜 로그인(구글/네이버/카카오), JWT 인증을 제공합니다.

---

목차

• 기술 스택
• 아키텍처
• 데이터 모델(ERD)
• 핵심 API
• 로컬 실행
• Docker
• 폴더 구조

---

기술 스택

---

아키텍처

flowchart LR
%% 클라이언트
client[Client]
%% 백엔드 서비스 그룹
subgraph FastAPI_Backend [NoteFlow Backend]
api[FastAPI Router]
auth[JWT / OAuth Handler]
subgraph AI_Engine [AI Processing Service]
ocr[OCR Engine\nPDF/Img Text]
whisper[Whisper Engine\nAudio STT]
llm[LLM Engine\nSummary/Quiz]
end
end
%% 외부 및 데이터 저장소
db[(MySQL)]
fs[(Local File System\n/uploads)]
oauth_ext{Social Login\nG / N / K}
hf_api[HuggingFace / LLM API]
%% 연결 관계
client -->|API Request| api
api --> auth
auth -.->|Auth Check| oauth_ext
api -->|Metadata| db
api -->|Binary Files| fs
%% AI 연동 흐름
api --> ocr
api --> whisper
api --> llm
%% LLM 외부 연동
llm <-->|Inference| hf_api
%% 스타일 지정
style FastAPI_Backend fill:#f5f5f5,stroke:#333,stroke-width:2px
style AI_Engine fill:#fff0f6,stroke:#c41d7f
style llm fill:#fff7e6,stroke:#d46b08

Loading

---

데이터 모델(ERD)

erDiagram
user ||--o{ folder : owns
user ||--o{ note : writes
user ||--o{ file : uploads
user ||--o{ checklist : has
folder ||--o{ note : contains
folder ||--o{ file : contains
note ||--o{ file : attaches
user {
int u_id PK
string id
string email
string password
enum provider
datetime created_at
datetime updated_at
}
folder {
int id PK
int user_id FK
string name
int parent_id
datetime created_at
datetime updated_at
}
note {
int id PK
int user_id FK
int folder_id FK
string title
text content
bool is_favorite
datetime last_accessed
datetime created_at
datetime updated_at
}
file {
int id PK
int user_id FK
int folder_id FK
int note_id FK
string original_name
string saved_path
string content_type
datetime created_at
}
checklist {
int id PK
int user_id FK
string title
bool is_clear
}

Loading

---

핵심 API

• 인증/회원가입: POST /api/v1/register, POST /api/v1/login, POST /api/v1/login/google, POST /api/v1/login/naver, POST /api/v1/auth/kakao/callback
• 노트: GET/POST/PATCH/DELETE /api/v1/notes, GET /api/v1/notes/recent, PATCH /api/v1/notes/{id}/favorite
• 요약/문제생성: POST /api/v1/notes/{id}/summarize, POST /api/v1/notes/{id}/summarize_sync, POST /api/v1/notes/{id}/generate-quiz
• 폴더: GET/POST/PATCH/DELETE /api/v1/folders (트리+노트 포함 응답)
• 파일: POST /api/v1/files/upload, GET /api/v1/files/download/{file_id}, GET /api/v1/files/list/{folder_id}
• OCR/STT: POST /api/v1/files/ocr?langs=kor+eng&max_pages=50, POST /api/v1/files/audio

토큰

• 모든 보호 API는 Authorization: Bearer <JWT> 헤더 요구

---

로컬 실행

1) 요구사항

• Python 3.10+
• MySQL 8.x (또는 호환 RDS)

2) 의존성 설치

cd Backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3) 환경 변수 (.env)

DATABASE_URL=mysql+mysqlconnector://USER:PASSWORD@localhost:3306/noteflow?charset=utf8mb4SECRET_KEY=CHANGE_MEACCESS_TOKEN_EXPIRE_MINUTES=120BASE_API_URL=http://localhost:8080# OAuthGOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_IDNAVER_CLIENT_ID=YOUR_NAVER_CLIENT_IDNAVER_CLIENT_SECRET=YOUR_NAVER_CLIENT_SECRETKAKAO_CLIENT_ID=YOUR_KAKAO_REST_API_KEYKAKAO_REDIRECT_URI=http://localhost:5174/kakao/callback# LLM (선택)HF_API_TOKEN=YOUR_HF_TOKENHF_MAX_NEW_TOKENS_LONG=32000

4) 서버 실행

uvicorn main:app --host 0.0.0.0 --port 8080 --reload

업로드 정적 경로

• 업로드 파일은 Backend/uploads/에 저장, 정적 서빙은 /static으로 노출됩니다.

OCR 의존 도구(선택)

• Poppler(pdftoppm), LibreOffice(soffice), hwp5txt가 있으면 더 폭넓은 포맷 지원
• 진단: GET /api/v1/files/ocr/diag

---

Docker

cd Backend
docker build -t noteflow-backend .
docker run --rm -p 8080:8080 --env-file .env noteflow-backend

주의

• OCR/Whisper 등은 컨테이너에 추가 시스템 패키지가 필요할 수 있습니다.

---

폴더 구조

Backend/
├── main.py # FastAPI 엔트리포인트(CORS, 라우터, 정적)
├── db.py # DB 연결/세션/초기화
├── models/ # SQLAlchemy 모델(User/Folder/Note/File/Checklist)
├── routers/ # auth, note, note_sync, folder, file, checklist
├── schemas/ # Pydantic 요청/응답 스키마
├── utils/ # JWT/패스워드/LLM/OCR 유틸
├── uploads/ # 업로드 저장소(정적 서빙)
├── requirements.txt # 의존성 목록
├── Dockerfile # 컨테이너 빌드 스펙
└── Makefile # 자주 쓰는 명령(선택)