마이그레이션은 냉장고 칸 재배치
모르는 단어와 친해지기
임베딩, 마이그레이션, CORS, JWT, 비동기, DI.
관제탑과 대화를 하다 보면 이런 단어들이 계속 나온다. 처음에는 그때그때 넘어갔다. 문맥에서 대충 감을 잡을 수 있었으니까. "CORS 설정을 해야 한다"고 하면, 뭔가를 설정해야 한다는 건 알겠고, CORS가 뭔지는 나중에 알아도 될 거라고 생각했다.
하지만 단어가 쌓이면서 상황이 달라졌다. 하나하나는 넘어갈 수 있어도, 열 개, 스무 개가 되면 대화 자체가 불투명해진다. AI가 설명해주는 내용이 "어렴풋이 이해는 가지만 개념이 확 잡히지 않는" 상태로 남아 있었다.
어느 저녁, 관제탑에 이렇게 말했다.
"한번도 개발과 프로그래밍을 경험해보지 못한 사람에게 네 설명은 어렴풋이 이해는 가지만, 개념이 확 잡히진 않아."
그리고 세 가지를 정리해달라고 했다.
첫째, 이 프로젝트에서 쓰이는 모든 기술을 한눈에 볼 수 있는 지도. 둘째, 터미널에서 자주 쓰는 명령어들과 왜 그것을 쓰는지. 셋째, 계속 나오는 기술 용어들이 뭘 말하는 건지.
AI가 만들어준 것은 기대 이상이었다. 전체 기술 스택을 하나의 비유 체계로 묶어줬다. "이 시스템은 식당이다." 거기서부터 시작했다.
프론트엔드는 식당의 홀이다. 손님이 들어와서 메뉴를 보고 주문하는 공간. 우리 프로젝트에서는 Next.js라는 도구로 만든 웹 화면이 이 역할을 한다. Tailwind CSS는 홀의 인테리어. 깔끔하게 보이도록 꾸미는 도구.
백엔드는 주방이다. 손님한테는 안 보이지만, 주문이 들어오면 요리를 해서 내보내는 곳. FastAPI라는 Python 프레임워크가 주방장이다.
데이터베이스는 냉장고이자 창고다. 재료(원본 데이터)와 완성된 요리(분석 결과)를 보관하는 곳. PostgreSQL이 큰 냉장고.
인증 서비스는 출입구 보안이다. 누가 들어오는지 확인하고, 권한이 있는 사람만 통과시키는 것. Supabase Auth가 이 역할.
배포는 건물 자체다. 아무리 좋은 주방과 홀이 있어도, 건물이 없으면 영업을 할 수 없다. Railway가 이 건물을 제공한다.
이 비유 체계가 잡히자 — 신기하게도 — 기술적 대화가 가능해졌다.
예를 들어, "이 기능은 프론트에서 처리할까 백엔드에서 처리할까"라는 질문. 이전에는 이 질문의 의미 자체를 이해하지 못했다. 하지만 식당 비유를 적용하면, "이건 홀에서 손님한테 바로 보여줄까, 아니면 주방에서 한 번 가공한 뒤에 내보낼까"가 된다. 이러면 판단이 가능하다.
마이그레이션이라는 단어도 이 맥락에서 이해됐다. 데이터베이스의 구조를 바꾸는 작업. 냉장고 칸을 재배치하는 것이다. 음식(데이터)은 그대로 두고, 칸(테이블 구조)의 배치를 바꾼다. 왜 필요하냐면, 처음에 냉장고를 구성할 때는 반찬 세 종류만 보관할 생각이었는데, 메뉴가 늘어나면서 칸이 부족해졌기 때문이다.
비동기는 진동벨이었다. 음식이 나오려면 시간이 걸린다. 주문하고 카운터 앞에서 기다리는 게 "동기" 방식이라면, 진동벨을 받고 자리에 가서 다른 일을 하다가 벨이 울리면 음식을 가지러 오는 게 "비동기" 방식이다. AI 분석처럼 시간이 오래 걸리는 작업에서 필수적인 개념이다.
CORS는 — 이건 비유가 조금 어려웠다 — 다른 주소에 있는 서버끼리 데이터를 주고받을 수 있게 허용하는 보안 설정이다. 우리 프로젝트에서 프론트(Vercel)와 백엔드(Railway)가 다른 주소에 있는데, 이 설정을 켜지 않으면 서로 말을 못 한다.
Next.js가 뭔지도 따로 물어봤다. 이건 React라는 도구 위에 편의 기능을 얹은 것이라고 했다. React가 건물의 골조라면, Next.js는 그 위에 엘리베이터, 중앙난방, 관리사무소를 추가한 것. 직접 골조부터 짓는 것(순수 React)보다 편하지만, 그 편의 기능들이 어떻게 작동하는지는 알아야 한다.
이 밤 이후로 달라진 건, AI와의 대화에서 수동적으로 듣는 쪽에서 능동적으로 판단하는 쪽으로 넘어갔다는 것이다. "프론트에서 처리할까 백엔드에서 처리할까"라는 질문에 내 의견을 낼 수 있게 됐다. 코드를 읽을 수 있어서가 아니다. 구조를 읽을 수 있게 되어서다.
그리고 그 구조를 읽는 언어는 코드가 아니라 비유였다.
🔧 이 에피소드의 기술 용어 해설
이 편은 본문 자체가 용어 해설이므로, 본문에서 다루지 못한 추가 용어를 보충합니다.
프론트엔드 (Frontend) 사용자가 직접 보고 조작하는 화면. 버튼, 입력창, 메뉴 — 눈에 보이는 모든 것. 이 프로젝트에서는 Next.js + Tailwind CSS로 만들었다.
백엔드 (Backend) 사용자에게는 보이지 않지만, 뒤에서 데이터를 처리하는 서버. 주문을 받아서 요리를 하는 주방. FastAPI(Python)로 만들었다.
API (Application Programming Interface) 프론트엔드와 백엔드가 대화하는 창구. 홀 직원이 주문서를 주방에 전달하는 것과 같다. "이 사용자의 분석 결과를 가져와줘"라는 요청을 보내면, 백엔드가 결과를 돌려보낸다.
마이그레이션 (Migration) 데이터베이스 구조를 변경하는 작업. 냉장고 칸을 재배치하는 것. 데이터는 그대로 두고 칸(테이블 구조)만 바꾼다.
CORS (Cross-Origin Resource Sharing) 다른 주소의 서버끼리 데이터를 주고받을 수 있게 허용하는 보안 설정. 프론트(Vercel)와 백엔드(Railway)가 다른 주소에 있으면, 이 설정 없이는 통신이 차단된다.
JWT (JSON Web Token) 디지털 신분증. 로그인하면 서버가 발급하고, 이후 요청마다 이 토큰을 보여주면 "이 사람은 로그인한 사용자"라고 확인한다.
비동기 (Asynchronous) 진동벨 시스템. 요청을 보내고 바로 결과를 받는 게 아니라, "처리 중"이라는 알림을 받고 다른 일을 하다가 완료되면 결과를 가져오는 방식. AI 분석처럼 시간이 오래 걸리는 작업에 필수적이다.