버리미 (Beorimi)

사진 한 장으로 대형폐기물 후보를 찾고, 강남구 기준의 품목·규격·예상 수수료를 확인해 신고 준비까지 돕는 웹 서비스입니다.

서비스 체험하기 · 발표 자료 보기

버리미는 사용자가 물건의 정확한 이름과 배출 규정을 일일이 찾는 대신, 사진에서 여러 물건을 찾아 신고에 필요한 목록으로 정리해 줍니다. AI가 모든 것을 결정하지는 않습니다. AI는 사진을 관찰하고, 서버는 공식 규칙을 바탕으로 판정하며, 사용자가 마지막으로 확정합니다.

현재 서비스는 서울 강남구 대형폐기물 기준으로 동작합니다. 분석 결과와 수수료는 신고 준비를 위한 참고 정보이며, 실제 배출 가능 여부와 최종 금액은 강남구 공식 신고 페이지에서 다시 확인해야 합니다.

빠르게 찾아보기

• 서비스가 작동하는 순서
• 전체 설계 구조
• 폴더별 역할
• 팀 협업 방식
• 로컬 실행 방법
• 검증 명령어
• 배포 구조

왜 만들었나요?

대형폐기물을 버릴 때는 생각보다 많은 정보를 직접 찾아야 합니다.

• 내가 버리려는 물건이 행정상 어떤 품목인지 알아야 합니다.
• 같은 소파나 책상도 크기와 규격에 따라 수수료가 달라집니다.
• 사진 속 물건 중에는 대형폐기물이 아니라 분리배출이나 전용 수거함 대상인 것도 있습니다.

버리미는 이 과정을 다음 세 단계로 줄입니다.

1. 버릴 물건이 모두 보이도록 사진을 찍거나 앨범에서 선택합니다.
2. 사진에서 물건을 찾아 강남구 품목과 규격에 맞는 예상 수수료를 보여줍니다.
3. 사용자가 품목·규격·수량을 확인한 뒤 공식 신고 페이지로 이동합니다.

주요 기능

• 한 장의 사진에서 여러 폐기물 후보 탐지
• 사진 위 위치 표시와 품목 카드 연결
• 품목, 규격, 수량을 사용자가 직접 수정
• 강남구 공식 품목 기준 예상 수수료 안내
• 대형폐기물이 아닌 품목의 별도 배출 방법 안내
• 분석 이력 확인과 공식 신고 페이지 연결
• Supabase Auth 기반 회원가입, 로그인, 로그아웃, 회원 탈퇴
• 회원가입 및 사진 업로드 전 개인정보 이용 동의

사용자에게 보이는 작동 흐름

1. 사진 입력 — 카메라로 촬영하거나 앨범에서 사진을 고릅니다.
2. 사진 준비 — 브라우저가 파일 형식과 크기를 확인하고, 업로드하기 좋은 크기로 줄입니다.
3. 분석 요청 — 사진을 비공개 저장소에 올리고 분석 작업을 등록합니다.
4. 물체 관찰 — VLM(Vision Language Model)이 물체의 이름, 위치, 크기, 재질, 상태 등을 정해진 JSON 형식으로 반환합니다.
5. 규칙 적용 — 서버가 관찰 결과를 강남구 수수료 목록과 대조해 배출 대상과 예상 금액을 계산합니다.
6. 사용자 확인 — 사진 속 번호와 품목 카드를 비교하면서 품목·규격·수량을 수정하거나 제외합니다.
7. 신고 준비 — 확정한 목록과 예상 합계를 확인하고 강남구 공식 신고 페이지로 이동합니다.

사진 분석은 몇 초 이상 걸릴 수 있으므로 화면이 결과를 기다리며 멈추지 않도록 비동기 작업으로 설계했습니다. 분석 요청을 받으면 서버는 먼저 202 queued를 반환하고, 브라우저는 일정 간격으로 완료 여부를 확인합니다. 쉽게 말해 “접수 번호를 먼저 받고, 준비가 끝났는지 다시 물어보는 방식”입니다.

전체 설계 구조

flowchart LR
    A[브라우저<br/>Next.js 화면] -->|로그인| B[Supabase Auth]
    A -->|업로드 토큰 요청| C[Vercel<br/>Route Handler]
    C -->|일회용 토큰 발급| D[Supabase Storage<br/>비공개 사진]
    A -->|토큰으로 직접 업로드| D
    A -->|분석 작업 생성| C
    C --> E[Supabase Postgres<br/>작업 상태와 결과]
    E -->|pg_net 비동기 호출| F[Supabase Edge Function]
    F -->|사진 관찰 요청| G[OpenAI Responses API]
    G -->|구조화된 관찰 결과| F
    F -->|검증·규칙 적용 후 저장| E
    A -->|완료될 때까지 polling| C
    C -->|현재 상태 또는 결과| A

Loading

구성 요소별 책임

구성 요소	하는 일	하지 않는 일
브라우저 / Next.js 화면	로그인, 사진 선택·전처리, 업로드, 진행 상태 표시, 결과 수정	OpenAI를 직접 호출하거나 비밀 키를 보관하지 않음
Vercel Route Handler	공개 API 제공, Supabase JWT 검증, 업로드 토큰 발급, 분석 작업 생성·조회	AI 분석을 동기식으로 처리하지 않음
Supabase	Auth, 비공개 Storage, Postgres, RLS, 작업 상태와 사용량 관리	화면을 렌더링하지 않음
Supabase Edge Function	사진 관찰 요청, 응답 스키마 검증, 보안 검사, 수수료 규칙 적용	브라우저에 모델 키를 노출하지 않음
VLM	사진 속 물체·위치·재질·상태·크기를 관찰	수수료와 최종 배출 방법을 임의로 결정하지 않음
공용 계약 (shared/)	Frontend, Backend, VLM이 주고받는 데이터 형식을 정의	특정 파트만의 구현 세부사항을 담지 않음

간단히 정리하면 Vercel은 화면과 공개 API의 입구, Supabase는 인증·저장·데이터·백그라운드 작업, VLM은 사진을 구조화된 관찰 데이터로 바꾸는 눈입니다.

사진 한 장이 분석되는 과정

1. 브라우저가 POST /api/uploads로 일회용 업로드 토큰을 요청합니다.
2. 브라우저가 토큰을 이용해 사진을 Supabase의 비공개 Storage에 직접 올립니다.
3. POST /api/analyses가 Postgres에 분석 작업을 만들고 즉시 202 queued를 반환합니다.
4. Postgres trigger가 pg_net을 통해 Supabase Edge Function을 비동기로 호출합니다.
5. Edge Function이 OpenAI Responses API에 사진 관찰을 요청합니다.
6. 정해진 JSON Schema와 보안 검사를 통과한 결과에만 강남구 규칙을 적용해 저장합니다.
7. 브라우저가 GET /api/analyses/{id}를 반복 호출하여 완료된 결과를 가져옵니다.

중요한 설계 원칙

1. AI의 관찰과 서비스의 판단을 분리합니다

VLM은 사진에서 보이는 정보만 반환합니다. 배출 가능 여부와 수수료는 백엔드가 관리하는 강남구 공식 카탈로그와 규칙으로 결정합니다. 사진만으로 규격을 하나로 확정하기 어렵다면 금액을 지어내지 않고 공식 금액 범위나 확인 필요 상태를 보여줍니다.

2. 사용자가 최종 결정권을 갖습니다

사진 속 물체와 결과 카드에는 같은 ID와 색상을 사용합니다. 사용자는 AI가 제안한 품목을 사진과 비교하고, 잘못된 항목을 수정하거나 제외한 뒤 최종 목록을 확정할 수 있습니다.

3. 분석 시간이 화면 응답 시간을 막지 않습니다

분석 요청과 결과 조회를 분리했습니다. 모델 응답이 늦어져도 사용자는 진행 상태를 볼 수 있고, 각 분석은 Postgres의 한 행으로 남아 운영 중에도 상태를 추적할 수 있습니다.

4. 비밀 값은 필요한 서버에만 둡니다

브라우저에는 OpenAI API key나 Supabase service role key를 노출하지 않습니다. OpenAI 관련 비밀 값은 Supabase Edge Function secret과 Vault에서 관리합니다.

5. 사진 속 문장을 명령으로 신뢰하지 않습니다

사진에 적힌 글자는 관찰 대상일 뿐 시스템 명령이 아닙니다. 프롬프트, JSON Schema, 서버 검증의 여러 단계에서 prompt injection 신호를 확인하며, 의심스러운 결과는 사용자에게 전달하지 않고 실패 처리합니다.

저장소 구조

beorimi/
├─ frontend/                 # Next.js 화면과 Vercel Route Handler API
│  └─ src/app/api/          # 업로드·분석·계정 공개 API
├─ supabase/                 # 운영 백엔드
│  ├─ migrations/           # DB 스키마, RLS, Storage, trigger, cron
│  └─ functions/analyze/    # 비동기 분석 Edge Function
├─ shared/                   # 세 파트가 공유하는 데이터 계약
│  ├─ api/openapi.yaml      # 공개 API 명세
│  └─ schemas/              # 요청·응답 JSON Schema
├─ vlm/                      # 프롬프트와 스키마를 실험하는 로컬 Python 도구
├─ docs/                     # 역할별 상세 가이드와 협업 요청 보드
├─ legacy/aws/               # 운영에서 제외된 이전 AWS 구현
├─ AGENTS.md                 # 저장소 전체 작업 규칙
└─ beorimi-slide.html        # 프로젝트 발표 자료

처음 참여했다면 아래처럼 찾으면 됩니다.

하고 싶은 일	먼저 볼 곳
화면이나 사용자 동작 수정	frontend/ → frontend/AGENTS.md
API, DB, 인증, Storage 수정	supabase/ → supabase/AGENTS.md
운영 분석 worker 수정	supabase/functions/analyze/
VLM 프롬프트·응답 실험	vlm/ → vlm/AGENTS.md
API 필드나 JSON 구조 변경	shared/api/openapi.yaml, shared/schemas/
다른 역할에 작업 요청	docs/cowork_ground.md

협업 방식

버리미는 Frontend, Backend, VLM 세 역할이 각자의 폴더를 맡고, shared/의 데이터 계약으로 연결되는 구조입니다.

역할	주요 책임	담당 경로
Frontend	화면, 사진 입력, 사용자 수정, API 호출, 결과 표시	frontend/
Backend	공개 API, 인증 검증, DB, Storage, 비동기 작업, 최종 배출 판정	frontend/src/app/api/, supabase/
VLM	이미지 관찰 프롬프트, 구조화된 출력, 관찰 품질과 안전성	운영: supabase/functions/analyze/, 실험: vlm/

기본 작업 순서

1. 범위를 정합니다. 작업이 Frontend, Backend, VLM 중 어디에 속하는지 먼저 정합니다.
2. 역할 규칙을 읽습니다. 해당 폴더의 AGENTS.md와 필요한 docs/<role>.md 부분만 확인합니다.
3. 각자 맡은 폴더에서 작업합니다. 파트별 브랜치에서 변경하고, 다른 역할의 코드를 임의로 함께 수정하지 않습니다.
4. 인터페이스 변경은 계약부터 수정합니다. 순서는 항상 shared 계약 → 데이터를 제공하는 코드 → 데이터를 사용하는 코드입니다.
5. 파트별 검증을 실행합니다. 작은 테스트부터 lint, build, 통합 확인 순으로 검증합니다.
6. 검토 후 main에 합칩니다. 머지할 때 구현뿐 아니라 공용 스키마와 문서가 함께 맞는지 확인합니다.

예를 들어 분석 결과에 새 필드를 추가한다면 다음 순서로 작업합니다.

shared/schemas 수정
        ↓
Supabase Edge Function이 새 필드를 제공
        ↓
Vercel API가 응답을 검증
        ↓
Frontend가 새 필드를 화면에 표시

다른 역할에 요청하는 방법

한 역할에서 다른 역할의 변경이 필요하면 docs/cowork_ground.md에 요청을 남깁니다.

• 요청자가 완료 조건과 필요한 데이터 형식을 적습니다.
• 담당 역할이 응답과 검증 증거를 기록합니다.
• 요청자가 결과를 확인한 뒤에만 요청을 DONE으로 닫습니다.
• 한 역할 안에서 끝나는 단순 TODO는 협업 보드에 올리지 않습니다.

이 방식은 “프론트가 백엔드 응답을 추측하는 문제”나 “VLM 출력이 바뀌었는데 스키마와 화면이 서로 다른 문제”를 줄여 줍니다.

로컬에서 실행하기

준비물

• Node.js 22.13 이상
• npm
• 연결할 Supabase 프로젝트
• Supabase CLI — migration이나 Edge Function을 수정할 때만 필요
• Python 3 — 로컬 VLM 실험을 할 때만 필요

1. 프론트엔드 환경 변수 만들기

PowerShell 기준으로 예시 파일을 복사합니다.

Copy-Item frontend/.env.example frontend/.env.local

frontend/.env.local에 자신의 Supabase 프로젝트 값을 넣습니다.

NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<publishable-key>
SUPABASE_SERVICE_ROLE_KEY=<server-only-service-role-key>

환경 변수	용도	브라우저 공개 여부
NEXT_PUBLIC_SUPABASE_URL	Supabase 프로젝트 주소	공개 가능
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	브라우저용 공개 키	공개 가능
SUPABASE_SERVICE_ROLE_KEY	Vercel API의 서버 작업용 키	공개 금지

SUPABASE_SERVICE_ROLE_KEY에는 절대 NEXT_PUBLIC_ 접두사를 붙이지 말고, 브라우저 컴포넌트에서도 읽지 마세요.

2. 패키지 설치 후 개발 서버 실행하기

npm.cmd --prefix frontend ci
npm.cmd --prefix frontend run dev

브라우저에서 http://localhost:3000을 열면 됩니다. 실제 로그인·업로드·분석 흐름은 환경 변수에 연결한 Supabase 프로젝트의 Auth, Storage, DB, Edge Function 구성이 완료되어 있어야 동작합니다.

3. 로컬 VLM 실험하기 (선택)

운영 분석은 Supabase Edge Function에서 실행됩니다. vlm/은 프롬프트와 응답 형식을 로컬에서 실험할 때 사용합니다.

Copy-Item vlm/.env.example vlm/.env
python -m pip install -r vlm/requirements.txt -r vlm/requirements-dev.txt
python -m vlm.app.cli <image-path>

vlm/.env에는 로컬 실험용 OPENAI_API_KEY를 설정해야 합니다. 실제 키가 들어간 .env 파일은 Git에 올리지 마세요.

검증 명령어

변경한 영역부터 확인한 뒤 필요한 전체 검증을 실행합니다.

# Frontend lint와 배포용 build
npm.cmd --prefix frontend run lint
npm.cmd --prefix frontend run build

# 로컬 VLM 테스트
python -m pytest vlm/tests

# Supabase 분석 worker 테스트
node --experimental-strip-types --test supabase/functions/analyze/*.test.ts

배포 구조

Supabase

1. 프로젝트를 연결하고 migration을 반영합니다.

   supabase link --project-ref <project-ref>
   supabase db push

2. 분석 Edge Function을 배포합니다.

   supabase functions deploy analyze

3. Edge Function secret에 OPENAI_API_KEY, OPENAI_VLM_MODEL, ANALYSIS_WORKER_SECRET을 등록합니다.

4. Supabase Vault에 다음 값을 등록합니다.

   • beorimi_analysis_worker_url: 배포된 analyze Edge Function URL
   • beorimi_analysis_worker_secret: ANALYSIS_WORKER_SECRET과 같은 값

5. Supabase Auth의 Site URL과 허용 Redirect URL에 Vercel 운영 URL을 등록합니다.

OpenAI key와 worker secret은 Vercel이나 브라우저 환경 변수에 등록하지 않습니다.

Vercel

1. 프로젝트 Root Directory를 frontend로 설정합니다.
2. Build Command를 npm run build로 설정합니다.
3. NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, SUPABASE_SERVICE_ROLE_KEY를 등록합니다.
4. 배포된 Vercel URL을 Supabase Auth 설정에 반영합니다.

현재 범위와 주의사항

• 현재 지역 기준은 서울 강남구입니다.
• 지원 이미지 형식은 JPEG, PNG, WebP이며 업로드 한도는 10MiB입니다.
• MVP 계정별 분석 한도는 누적 30회입니다.
• 원본 이미지와 분석 기록은 기본 30일 뒤 정리됩니다.
• 예상 수수료는 참고값이며 공식 신고 과정에서 다시 확인해야 합니다.
• 이전 FastAPI, Lambda, S3, SQS, DynamoDB, Cognito, CloudFormation, Amplify, App Runner 구현은 legacy/aws/에 보존되어 있지만 현재 운영 경로에는 사용하지 않습니다.

앞으로 확장할 수 있는 방향

• 앱에서 신고와 수거 일정까지 한 번에 연결
• OpenAI 외 로컬 VLM으로 교체 가능한 분석 provider 확장
• 강남구 외 다른 자치구의 품목·수수료 규정 추가

관련 문서

• 시스템 아키텍처
• API 계약 설명
• OpenAPI 명세
• 프론트엔드 가이드
• 백엔드 가이드
• VLM 가이드
• 역할 간 협업 요청 보드
• 프로젝트 발표 자료