Coffeebara

Coffeebara는 카페, 추출, 맛, 메모를 구조적으로 축적할 수 있도록 설계한 개인 커피 아카이브 및 브루잉 기록 서비스입니다.

이 프로젝트는 사용자가 자신의 커피 경험을 검색하고, 저장하고, 기록하고, 나중에 다시 돌아볼 수 있는 흐름을 만드는 것을 목표로 합니다.

Coffeebara는 공개 추천 플랫폼이 아니라, 사용자가 자신의 커피 경험을 장기적으로 축적해 가는 개인 기록 서비스에 초점을 둡니다.

• 어떤 원두를 사용했는지
• 어떤 방식으로 추출했는지
• 어떤 맛과 향을 느꼈는지
• 어느 카페에서 샀는지
• 어느 카페에서 마셨는지
• 시간이 지나며 어떤 취향 경향이 나타나는지

제품 방향 메모는 product-direction-notes.md, 현재 작업 기준과 해석 원칙은 AGENTS.md에 정리되어 있습니다.

프로젝트 목적

Coffeebara는 개인 커피 기록을 더 구조적으로 남기기 위한 제품형 프로젝트입니다.
이 저장소는 단순한 UI 데모나 실험용 코드 모음이 아니라, 실제 사용 흐름을 갖춘 개인 커피 아카이브로 발전시키는 것을 목표로 합니다.

이 프로젝트는 아래 두 가지 관점에서 함께 볼 수 있습니다.

1. 서비스 / 제품 관점

Coffeebara는 사용자가 카페, 추출, 맛, 메모를 나중에 다시 꺼내볼 수 있도록 돕는
개인 커피 기록 서비스를 지향합니다.

현재는 카페 검색, 저장, 텍스트/원두 기록과 이미지 첨부 흐름까지 구현되어 있으며,
앞으로 브루잉 기록을 포함한 record type 확장으로 기능을 완성해 갈 예정입니다.

즉, Coffeebara는 “어떤 카페가 좋은가”를 추천하는 서비스라기보다,
“내가 무엇을 마셨고 어떻게 기록했는가”를 남기는 서비스입니다.

2. 기술 / 구현 관점

이 프로젝트는 Spring Boot + Next.js 기반에서
OAuth 로그인, 장소 캐시, 회원/게스트 상태 분리, 기록 모델 설계,
카드형 기록 UI와 정렬/삭제 흐름 등을 실제 제품 구조로 정리해 가는 작업이기도 합니다.

즉, Coffeebara는 서비스 기획을 검증하는 프로젝트이면서,
기록 중심 웹 애플리케이션을 어떻게 구조화할지 정리하는 기술 포트폴리오이기도 합니다.

현재 진행 상황

현재 코드베이스는 개인 커피 기록 서비스를 중심으로 기능과 구조를 확장해 가는 단계에 있습니다.

1. 서비스 / 제품 측면

이미 동작 중인 것:

• Kakao OAuth 로그인
• 카페 키워드 검색
• 회원 저장 카페 저장/조회/삭제
• 저장 카페 삭제 전 연결된 기록 수 확인
• 저장한 카페 기준 텍스트/원두 기록 작성/수정/삭제/정렬
• 원두 기록 이미지 드래그앤드롭, 업로드, 삭제 예정/복원
• 게스트 저장 카페를 localStorage에 유지
• 저장 카페 목록, 상세 진입 UI, 계정 메뉴 요약 UI

현재 README는 사용자에게 제공하는 기본 흐름을 중심으로 설명합니다. 일부 탐색 관련 구현은 코드베이스에 남아 있을 수 있으나, 현재 제품 범위에는 포함하지 않습니다.

다음 단계:

• 브루잉 기록 CRUD
• 기록 타입 확장
• Docker 기반 실행 환경 정리
• 게스트 샘플/데모 기록 흐름 완성
• 취향 분석/AI 요약

2. 기술 / 구현 측면

이미 반영한 것:

• app_user 기반 계정 저장
• cafe 테이블 기반 장소 캐시 적재
• DB 우선 카페 상세 조회 + stale 시 Kakao refresh
• user_saved_cafe 기반 회원 저장 카페 관계 관리
• cafe_record + cafe_note + bean_record 구조 기반 mixed record 저장
• media_asset + media_attachment 구조 기반 이미지 첨부 메타데이터/연결 모델 활성화
• CAFE_RECORD 기준 로컬 이미지 업로드 API, 첨부 조회, 첨부 삭제 흐름 반영
• 회원 / 게스트 상태 분리
• 기록 카드 정렬 및 삭제 흐름 반영
• 홈 검색/지도 공유 상태를 좁은 범위의 Zustand store로 분리
• frontend 앱 기준 active CRUD의 Prisma 전환 완료

다음 정리 대상:

• 기록 타입 확장을 고려한 모델 구조 정리
• 브루잉 기록 도입에 맞춘 UI 흐름 확장
• 추가 record type 확장에 맞춘 상태 구조 정리
• 취향 분석 / AI 요약의 역할과 범위 정의

대표 화면

화면 예시

추가 화면 예시 보기

로그인 / 회원

로그인 화면

회원 홈 화면

회원 계정 메뉴

카페 검색 / 저장

카페 검색 결과

저장한 카페 삭제 확인

기록 기능

기록 화면 진입

새 기록 타입 선택

텍스트 기록 편집 화면

텍스트 기록 목록

기록 순서 변경 결과

기록 삭제 메뉴

기록 삭제 결과

게스트 모드

게스트 홈 화면

현재 제품 해석

현재 저장소는 아래 기준으로 이해할 수 있습니다.

• cafe는 장소 캐시/마스터 테이블입니다.
• user_saved_cafe는 회원이 저장한 카페 관계 테이블입니다.
• cafe_record는 회원이 카페 맥락에 연결해 남기는 기록의 부모 레이어입니다.
• cafe_note는 현재 구현된 텍스트 기록 페이로드 레이어입니다.
• bean_record는 현재 구현된 원두 기록 페이로드 레이어입니다.
• media_asset는 로컬 파일 저장 메타데이터 테이블입니다.
• media_attachment는 기록과 파일을 연결하는 범용 첨부 테이블입니다.
• 게스트 저장 카페는 계정 데이터가 아니라 localStorage 기반 임시 상태입니다.
• 카페는 제품의 중심이 아니라, 기록을 위한 맥락 데이터입니다.

즉, Coffeebara는 “카페 추천 서비스”가 아니라 “개인 커피 기록 서비스”입니다.

현재 데이터 접근 방향

현재 운영 기준에서 새 UI와 active CRUD는 frontend/의 Next.js 앱 안에 있는 Prisma 경로를 중심으로 이해하면 됩니다.

저장소 루트의 Spring Boot + MyBatis 백엔드는 여전히 남아 있지만, 현재는 전체 CRUD의 중심이 아니라 예외 경계에 가깝습니다.

이 의미는 다음과 같습니다.

• MyBatis가 아직 제거된 것은 아닙니다.
• active CRUD 기준 Prisma 전환은 사실상 완료된 상태입니다.
• 예외적으로 Kakao 로그인 시 app_user upsert와 cafe 마스터 upsert만 MyBatis 경계에 남아 있습니다.
• 이후 새로 붙는 UI와 기능 슬라이스는 Prisma 기준으로 확장하는 방향을 기본으로 합니다.

이 예외 경계가 남아 있는 이유도 의도적입니다.

• Kakao OAuth와 UserInfo 처리는 현재 Spring Security 흐름 안에 깊게 결합되어 있습니다.
• app_user upsert는 그 로그인 흐름의 일부로 붙어 있어, 이를 억지로 frontend 쪽으로 옮기면 인증 소유권과 외부 API 처리 위치까지 다시 설계해야 합니다.
• cafe 마스터 upsert도 Kakao 장소 조회/갱신과 함께 Spring 쪽에서 이미 안정적으로 묶여 있습니다.
• 따라서 이 프로젝트에서는 archive-facing CRUD를 Prisma로 옮기고, Kakao 연동에 직접 맞물린 경계만 Spring/MyBatis에 남기는 방향을 선택했습니다.

기술 스택

Backend

• Java 21
• Spring Boot 4.0.5
• Gradle
• MyBatis
• MariaDB
• p6spy

Frontend

• Next.js 16
• React 19
• Tailwind CSS 4
• ESLint 9
• Zustand 5
• Prisma ORM (active CRUD migration completed in frontend, except selected upsert boundaries)

주요 API

Auth

• GET /api/auth/status
• POST /api/auth/guest
• POST /api/auth/logout
• GET /api/auth/logout/kakao-account
• PATCH /api/auth/profile/display-name

Cafe

• GET /api/cafes/search
• GET /api/cafes/{placeId}
• GET /api/cafes/map
• GET /api/cafes/map/search
• POST /api/cafes

Member Saved Cafes

• GET /api/user-saved-cafes
• POST /api/user-saved-cafes
• GET /api/user-saved-cafes/{placeId}/delete-check
• DELETE /api/user-saved-cafes/{placeId}

Place Records

• GET /api/place-records/{placeId}
• POST /api/place-records/{placeId}
• DELETE /api/place-records/{placeId}/{recordId}

Record Attachments

• GET /api/records/{recordId}
• POST /api/records/{recordId}/attachments
• GET /api/records/{recordId}/attachments/{attachmentId}
• DELETE /api/records/{recordId}/attachments/{attachmentId}

현재 이미지 첨부는 Spring media preprocessing과 frontend Prisma linkage를 함께 사용하는 구조입니다.

• 저장 루트는 app.media.storage-root 프로퍼티를 사용합니다.
• DB에는 절대경로가 아니라 storage_key 상대경로만 저장합니다.
• 실제 파일 경로는 storageRoot + storageKey 조합으로 해석합니다.
• 업로드 전처리는 Spring backend가 처리하고, 첨부 연결은 frontend local route + Prisma가 담당합니다.
• 첨부 조회와 삭제는 media_asset, media_attachment 테이블이 준비된 상태를 전제로 합니다.

저장소 구조

coffeebara/
├─ src/
│  └─ main/
│     ├─ java/com/coffeebara/
│     └─ resources/
├─ frontend/
│  ├─ app/
│  ├─ public/
│  └─ package.json
├─ db/
│  └─ schema.sql
├─ docs/
│  ├─ archive/
│  └─ readme-assets/
│     ├─ auth/
│     ├─ cafe/
│     ├─ home/
│     └─ record/
├─ AGENTS.md
├─ product-direction-notes.md
└─ README.md

실행 방법

Backend

저장소 루트에서:

./gradlew bootRun

Frontend

frontend/에서:

cd frontend
npm install
npm run dev

로컬 실행에 필요한 것

최소한 아래 설정이 필요합니다.

• Kakao REST API Key
• Kakao JavaScript Key
• Kakao OAuth 연동 설정
• MariaDB 연결 정보
• frontend에서 Prisma가 사용할 DB 연결 설정

기본 포트:

• Backend: 18080
• Frontend: 3000

이 프로젝트가 아닌 것

현재 Coffeebara는 아래 방향을 목표로 하지 않습니다.

• 카페 추천 플랫폼
• 공개 리뷰 서비스
• 소셜 피드/팔로우 서비스
• 커뮤니티 중심 제품
• AI가 핵심 가치인 제품

정리

Coffeebara는 개인 커피 아카이브 및 브루잉 기록 서비스입니다.
현재는 카페 검색, 장소 캐시, 회원 저장 카페, 회원 텍스트/원두 기록, 원두 기록 이미지 첨부, 게스트 저장 흐름까지 정리된 상태이며, active CRUD는 Prisma 기준으로 전환되었습니다. MyBatis는 Kakao 로그인 시 app_user upsert와 cafe 마스터 upsert 같은 예외 경계에만 남아 있고, 이후 새 기능과 UI는 Prisma 기준으로 붙여 가는 방향입니다.

License

이 프로젝트는 MIT License를 따릅니다. 자세한 내용은 LICENSE를 참고해 주세요.