웹앱에서 버튼을 누른 뒤 화면, API, 서버, 데이터베이스를 거쳐 결과가 돌아오는 흐름을 비개발자 눈높이로 설명합니다.
웹앱 구조 이해의 출발점은 화면에서 보낸 요청이 서버와 데이터베이스(DB)를 거쳐 다시 응답으로 돌아오는 흐름입니다.
연재 안내: 27편 전체 순서와 현재 공개된 글은 비개발자 바이브코딩 로드맵에서 확인할 수 있습니다.
필요한 기능을 아직 줄이지 못했다면 MVP 기능 정하기부터 확인하세요.
한 줄 답변
웹앱은 사용자가 화면에서 행동하면 브라우저가 API 요청을 보내고, 서버가 규칙을 검사해 데이터베이스를 읽거나 수정한 뒤, 응답을 화면에 돌려주는 구조로 움직입니다. 이 흐름을 알면 오류가 난 위치와 AI가 수정해야 할 범위를 구분할 수 있습니다.
예약 버튼을 누르면 무슨 일이 일어날까
공방 예약 문의 앱에서 고객이 이름과 날짜를 입력하고 신청 버튼을 눌렀다고 해보겠습니다. 눈에는 버튼 한 번만 보이지만 내부에서는 다음 순서가 진행됩니다.
- 화면이 입력값을 모은다.
- 브라우저가 서버의 API 주소로 요청을 보낸다.
- 서버가 빈 값, 날짜, 권한 같은 규칙을 검사한다.
- 문제가 없으면 데이터베이스에 저장한다.
- 서버가 성공 또는 실패 응답을 보낸다.
- 화면이 응답에 맞춰 완료 문구나 오류를 표시한다.
이 여섯 단계를 화살표로 그릴 수 있으면 전체 코드를 몰라도 웹앱의 현재 상태를 설명할 수 있습니다.
화면은 입력과 결과를 보여준다
프론트엔드는 사용자가 보는 화면입니다. 입력값을 모으고 버튼 동작을 시작하며 서버에서 받은 결과를 보여줍니다. 사용하기 편한 안내와 기본적인 빈 값 확인도 할 수 있습니다.
그러나 중요한 규칙을 화면 검사에만 맡기면 안 됩니다. 사용자는 브라우저의 요청을 바꾸거나 화면을 거치지 않고 API를 직접 호출할 수 있기 때문입니다. 중복 예약 방지, 가격 계산, 권한 확인은 서버에서도 반드시 검사해야 합니다.
API는 화면과 서버의 약속이다
API는 화면이 서버에 무엇을 어떤 형식으로 보낼지 정한 약속입니다. 예를 들어 POST /reservations에 이름과 날짜를 보내면 새 예약을 만든다고 정할 수 있습니다.
요청에는 주소, 방식, 데이터가 있고 응답에는 상태 코드와 결과가 있습니다. 화면과 서버가 서로 다른 이름을 사용하면 데이터가 있어도 보이지 않을 수 있습니다. 화면은 customerName을 보내는데 서버가 name만 찾는 경우가 대표적입니다.
서버는 규칙과 권한을 확인한다
백엔드 서버는 요청을 받으면 현재 사용자가 누구인지, 이 작업을 할 권한이 있는지, 입력값이 규칙에 맞는지 확인합니다. 이후 데이터베이스에 필요한 명령을 보내고 결과를 정리해 응답합니다.
로그인 성공과 권한 허용은 다릅니다. 로그인한 고객이 다른 고객의 예약까지 볼 수 있어서는 안 됩니다. 화면에서 버튼을 숨기는 것만으로는 부족하고 서버가 데이터 접근 범위를 제한해야 합니다.
데이터베이스는 기억을 맡는다
데이터베이스에는 예약의 이름, 날짜, 상태처럼 나중에도 남아야 할 정보가 저장됩니다. 어떤 항목이 필수인지, 서로 어떤 관계인지, 누가 읽고 바꿀 수 있는지 정해야 합니다.
저장이 성공했다는 응답을 받았는데 새로고침 후 데이터가 사라진다면 실제 데이터베이스가 아니라 화면의 임시 상태에만 값이 있었을 수 있습니다. 반대로 DB에는 값이 있는데 화면에 없다면 조회 API나 응답 처리에서 문제가 생겼을 가능성이 큽니다.
오류 위치를 흐름으로 찾는 법
- 요청이 만들어지지 않는다: 화면 이벤트와 API 호출 함수를 확인한다.
- 요청은 갔지만 오류 응답이 온다: 서버 입력 검사·인증·권한과 로그를 확인한다.
- 성공 응답인데 화면이 비어 있다: 실제 JSON 구조와 화면 표시 코드를 비교한다.
“앱이 안 된다”가 아니라 “요청은 서버에 도착했고 DB 저장도 됐지만 응답의 data.items를 화면이 items로 읽는다”고 설명하면 수정 범위가 작아집니다.
설계 방법 글과 다른 점
이번 글은 앱이 실행될 때 데이터가 이동하는 순서만 다룹니다. 화면·데이터·권한·기능·API를 어떤 칸으로 나눠 설계할지는 스파게티 코드를 피하는 5칸 구조에서 별도로 확인할 수 있습니다.
역할이 나뉜 구조는 유지보수에도 유리합니다. 화면 문구를 고칠 때 DB 저장 코드까지 흔들리지 않고, 서버 오류를 화면 파일 전체 교체 없이 찾을 수 있기 때문입니다.
개발자 도구로 흐름 한 번 확인하기
브라우저 개발자 도구의 Network 탭을 열고 목록을 불러오거나 저장 버튼을 누릅니다. 새로 생긴 요청 한 건을 선택해 주소, 요청 방식, 보낸 값, 상태 코드, 응답 본문을 차례로 봅니다. 비밀 토큰과 개인정보는 복사하거나 공개하지 않습니다.
그 요청과 연결된 서버 로그에서 같은 시각의 기록을 찾고, 데이터베이스에 가짜 데이터가 실제로 저장됐는지 확인합니다. 화면에서 시작한 행동을 세 장소에서 이어볼 수 있다면 웹앱 구조를 코드가 아닌 실제 흐름으로 이해한 것입니다.
웹앱 구조 이해 최종 점검
웹앱 구조 이해가 됐는지는 기능 하나를 선택해 화면 입력, API 주소, 서버 처리, DB 저장, 화면 응답을 순서대로 가리킬 수 있는지로 확인합니다. 웹앱 구조 이해 없이 AI가 지목한 파일만 수정하면 실제 원인이 다른 구간에 있을 때 새 오류를 만들기 쉽습니다.
브라우저 개발자 도구의 요청과 응답, 서버 로그, DB 결과를 같은 시각 기준으로 기록해보세요. 값이 마지막으로 정상인 지점을 찾으면 다음 구간만 조사할 수 있어 코드 전체를 무작정 바꾸지 않아도 됩니다.
실행 흐름을 이해했다면 다음 글인 프로젝트 파일 정리: 초보 폴더 구조에서 화면·통신·공용 기능을 찾기 쉬운 위치로 나눠보세요.
바이브코딩 전체 순서 보기
바이브코딩 뜻, 하는법, 도구 선택, API 연결, 데이터베이스, 배포 흐름은 바이브코딩 가이드에서 이어서 볼 수 있습니다.
