웹앱 코드 기본 구조: 폴더 구성부터 파일 안의 구성까지 (나만의 스케줄러 만들기 4편)
AI가 만든 웹앱 코드는 한 줄씩 읽기 전에 구조부터 보면 됩니다. Next.js 스케줄러 예시로 폴더별 역할, 자료 모양을 정하는 types 파일, 화면 파일 하나를 일곱 부분으로 나눠 읽는 법, 체크칸 하나가 저장되기까지 파일이 이어지는 순서를 정리했습니다.

AI가 만든 웹앱 코드는 어디부터 읽어야 할까요? 처음부터 한 줄씩 해석하지 말고, 폴더와 파일의 역할부터 확인하면 됩니다. Next.js 프로젝트는 화면(app), 부품(components), 공통 기능(lib), 자료 모양(types)으로 나뉘는 경우가 많습니다. 여기에 화면 파일 하나를 "준비 → 기억과 동작 → 화면 그리기" 순서로 읽는 법을 더하면, 버튼을 눌렀을 때 어느 파일이 일하는지 따라갈 수 있습니다. 「나만의 스케줄러 만들기」 시리즈 4편입니다.
코드보다 구조를 먼저 보는 이유는?
AI에게 기획서를 건네면 파일 수십 개가 한꺼번에 생깁니다. 이때 문법부터 공부하려 하면 금방 지칩니다. 기획자로 일하던 저도 화면 설계서는 익숙했지만 코드는 낯설었고, 길을 찾게 해 준 것은 문법보다 구조였습니다.
구조를 알면 세 가지가 쉬워집니다.
- 고칠 곳 찾기: 화면이 이상하면 app이나 components, 저장이 안 되면 lib부터 봅니다.
- AI에게 요청하기: "안 돼요" 대신 "어느 파일의 어느 부분"을 짚어 말할 수 있습니다.
- 기능 더하기: 새 기능이 어떤 파일들을 함께 바꾸는지 미리 가늠할 수 있습니다.
이 글의 예시는 3편 기획서(TypeScript, Next.js, Supabase)를 바탕으로 단순하게 만든 것입니다. AI가 실제로 만든 프로젝트는 이름과 나누는 방식이 조금씩 다를 수 있습니다.
1. 폴더마다 무슨 일을 맡을까?
스케줄러 프로젝트는 대략 이렇게 나뉩니다.
my-scheduler/
├─ app/ 페이지와 화면 구성 (주소마다 폴더 하나)
│ ├─ layout.tsx 모든 화면을 감싸는 틀
│ ├─ today/page.tsx 오늘 화면 (/today)
│ ├─ week/page.tsx 이번 주 화면 (/week)
│ ├─ login/page.tsx 로그인 화면 (/login)
│ └─ edit/page.tsx 일정 추가·수정 화면 (/edit)
├─ components/ 화면에서 쓰는 부품
│ ├─ ScheduleItem.tsx 일정 한 줄 (체크칸 + 제목)
│ └─ ScheduleForm.tsx 입력칸 묶음
├─ lib/ 연결·저장·조회 같은 공통 기능
│ ├─ supabase.ts 데이터베이스 연결
│ └─ schedules.ts 일정 저장하기, 불러오기
├─ types/
│ └─ schedule.ts 자료의 모양 정의
├─ public/ 이미지와 아이콘
├─ package.json 도구 목록과 실행 명령
└─ .env.local 내 컴퓨터의 연결 설정 (GitHub에 올리지 않음)| 위치 | 역할 | 이럴 때 먼저 열어 봅니다 |
|---|---|---|
| app | 페이지와 화면 구성 | 화면 전체의 배치나 주소가 이상할 때 |
| components | 여러 화면에서 쓰는 부품 | 일정 한 줄, 입력칸 모양이 이상할 때 |
| lib | 연결·저장·조회 같은 공통 기능 | 저장이 안 되거나 불러온 내용이 틀릴 때 |
| types | 자료의 모양 정의 | 일정에 새 항목을 더할 때 |
| public | 이미지와 아이콘 | 앱 아이콘을 바꿀 때 |
| package.json | 도구 목록과 실행 명령 | 개발 서버 실행 명령을 확인할 때 |
| .env.local | 내 컴퓨터의 연결 설정 | 데이터베이스 연결이 안 될 때 |
알아 둘 점
- Next.js의 App Router에서는 app 안의 폴더가 주소가 되고, 그 폴더의 page.tsx가 화면이 됩니다. app/week/page.tsx가 /week 화면인 식입니다.
- 폴더 이름은 정해진 규칙이 아닙니다. src 폴더 안에 모두 넣거나, lib 대신 다른 이름을 쓰기도 합니다. app에는 서버에서 도는 코드가 들어가기도 합니다. 이름보다 화면, 부품, 데이터 처리가 나뉘어 있는지를 봅니다.
- .env.local은 GitHub에 올리지 않습니다. 또 이름이
NEXT_PUBLIC_으로 시작하는 값은 브라우저로 보내지는 코드에 들어가므로, 비밀 키에는 이 이름을 쓰지 않습니다.

2. 기획서의 ‘저장할 정보’는 코드에서 어디에 있을까?
types 폴더에 있습니다. 3편에서 정한 제목, 날짜, 시작 시간, 메모, 완료 여부가 아래처럼 "일정 하나의 모양"으로 옮겨집니다.
// types/schedule.ts
export type Schedule = {
id: string;
title: string;
date: string;
startTime: string | null;
memo: string | null;
done: boolean;
};| 코드 | 뜻 |
|---|---|
id: string | 일정 번호. 글자로 다룹니다 |
title: string | 제목. 글자입니다 |
date: string | 날짜. 글자로 다룹니다 |
startTime: string 또는 null | 시작 시간. 글자이거나 비어 있을 수 있습니다 |
memo: string 또는 null | 메모. 글자이거나 비어 있을 수 있습니다 |
done: boolean | 완료 여부. true(완료) 또는 false(미완료) |
string은 글자, boolean은 참·거짓, null은 값이 없음을 뜻합니다. string | null의 세로줄은 "또는"입니다.
이렇게 모양을 정해 두면 제목을 빠뜨리거나 done에 글자를 넣는 실수를 TypeScript가 미리 알려 줍니다. 다만 한계도 있습니다. date: string은 글자라는 것만 확인하므로 "2026-99-99" 같은 잘못된 날짜는 걸러지지 않습니다. 날짜가 실제로 맞는지는 따로 검사해야 합니다. 또 이 모양은 화면에서 쓰는 정보만 담았고, 누구의 일정인지 구분하는 사용자 정보는 저장할 때 함께 다룹니다.
3. 화면 파일 하나는 어떻게 읽을까?
오늘 화면 파일(app/today/page.tsx)을 일곱 부분으로 나눠 봅니다. 구조를 보여 주기 위한 예시라서, 가져오는 부품과 저장 함수는 다른 파일에 있다고 가정합니다.
// ① 브라우저에서 상호작용하는 부분의 시작
"use client";
// ② 다른 파일과 도구에서 필요한 것을 가져오기
import { useEffect, useState } from "react";
import ScheduleItem from "@/components/ScheduleItem";
import { getTodaySchedules, toggleDone } from "@/lib/schedules";
import type { Schedule } from "@/types/schedule";
// ③ 오늘 화면을 만드는 함수
export default function TodayPage() {
// ④ 지금 보여 줄 일정 목록 기억하기
const [schedules, setSchedules] = useState<Schedule[]>([]);
// ⑤ 화면이 열리면 오늘 일정 불러오기
useEffect(() => {
getTodaySchedules().then(setSchedules);
}, []);
// ⑥ 완료 표시를 누르면 저장하고 목록 고치기
async function handleToggle(schedule: Schedule) {
const updated = await toggleDone(schedule);
setSchedules((prev) =>
prev.map((item) => (item.id === updated.id ? updated : item))
);
}
// ⑦ 화면에 보여 줄 내용
return (
<main>
<h1>오늘 할 일</h1>
{schedules.map((schedule) => (
<ScheduleItem key={schedule.id} schedule={schedule} onToggle={handleToggle} />
))}
</main>
);
}| 부분 | 찾을 단어 | 하는 일 | 문제가 생기면 |
|---|---|---|---|
| ① 준비 | "use client" | 클릭·상태처럼 브라우저 기능을 쓰는 부분이라고 표시 | 버튼이 반응하지 않거나 오류가 날 때 |
| ② 준비 | import | 부품, 함수, 자료 모양을 다른 파일에서 가져옴 | "찾을 수 없다"는 오류가 날 때 |
| ③ 준비 | function TodayPage | 오늘 화면을 만드는 함수 | — |
| ④ 기억 | useState | 지금 보여 줄 일정 목록을 기억 | 화면이 바뀌어야 하는데 그대로일 때 |
| ⑤ 동작 | useEffect | 이 예시에서는 화면이 열린 뒤 오늘 일정을 불러옴 | 일정이 안 보일 때 |
| ⑥ 동작 | handleToggle | 완료 표시를 눌렀을 때 할 일을 묶음 | 눌러도 반응이 없을 때 |
| ⑦ 그리기 | return | 제목과 일정 목록을 어떤 모양으로 보여 줄지 적음 | 글자나 순서가 이상할 때 |
정리하면 위쪽은 준비, 가운데는 기억과 동작, 아래쪽은 화면 그리기입니다. 모든 파일이 이렇게 생기지는 않습니다. 서버에서 자료를 미리 불러오도록 만들면 ①과 ⑤가 없을 수 있고, 작은 부품 파일은 그리기만 하기도 합니다.

4. 저장하는 줄과 화면을 바꾸는 줄은 무엇이 다를까?
⑥번 안의 두 줄은 둘 다 일정을 바꾸는 것처럼 보이지만, 바꾸는 대상이 다릅니다.
const updated = await toggleDone(schedule);setSchedules((prev) =>
prev.map((item) => (item.id === updated.id ? updated : item))
);| 구분 | 첫째 줄: 저장 | 둘째 줄: 화면 갱신 |
|---|---|---|
| 코드 | toggleDone(schedule) | setSchedules(...) |
| 바꾸는 것 | 데이터베이스에 저장된 일정 | 화면이 기억하는 일정 목록 |
| 하는 일 | 저장 함수를 실행하고 결과를 기다림 | 목록에서 같은 번호의 일정만 새 값으로 바꿈 |
| 빠지면 | 새로고침하면 원래대로 돌아감 | 저장은 됐지만 화면은 그대로 보임 |
"체크는 되는데 새로고침하면 풀린다"면 첫째 줄 쪽을, "저장은 됐는데 화면이 그대로"라면 둘째 줄 쪽을 의심해 볼 수 있습니다.
5. 체크칸을 누르면 어떤 순서로 처리될까?
먼저 함께 움직이는 파일 두 개를 보겠습니다.
// components/ScheduleItem.tsx : 일정 한 줄
import type { Schedule } from "@/types/schedule";
type Props = { schedule: Schedule; onToggle: (schedule: Schedule) => void };
export default function ScheduleItem({ schedule, onToggle }: Props) {
return (
<label>
<input type="checkbox" checked={schedule.done} onChange={() => onToggle(schedule)} />
{schedule.title}
</label>
);
}// lib/schedules.ts : 완료 여부를 데이터베이스에 저장
import { supabase } from "./supabase";
import type { Schedule } from "@/types/schedule";
export async function toggleDone(schedule: Schedule): Promise<Schedule> {
const { data, error } = await supabase
.from("schedules")
.update({ done: !schedule.done })
.eq("id", schedule.id)
.select()
.single();
if (error) throw error;
return data;
}저장이 성공한 뒤 화면을 바꾸는 방식이라면 순서는 이렇습니다.
| 순서 | 파일·함수 | 하는 일 |
|---|---|---|
| 1 | components/ScheduleItem.tsx | 체크칸이 눌렸다고 화면에 알림 (onToggle) |
| 2 | app/today/page.tsx의 handleToggle | 저장 함수를 부름 |
| 3 | lib/schedules.ts의 toggleDone | 데이터베이스에 완료 여부 변경을 요청 |
| 4 | 데이터베이스(Supabase) | 접근 규칙에 맞으면 값을 바꾸고 바뀐 일정을 돌려줌 |
| 5 | setSchedules | 돌려받은 일정으로 화면의 목록을 고침 |
| 6 | React | 바뀐 목록을 화면에 다시 그림 |
주의할 점: 4번에서 "내 일정만 바꿀 수 있게" 하려면 데이터베이스에 접근 규칙(Supabase의 행 단위 보안, RLS)을 따로 설정해야 합니다. 로그인 화면을 붙이는 것만으로 해결되지는 않습니다. 이 부분은 6편 저장과 로그인에서 다룹니다.
이 순서를 알면 AI에게도 구체적으로 요청할 수 있습니다. 예: "체크 표시는 되는데 새로고침하면 풀려. toggleDone과 화면이 열릴 때 불러오는 부분을 확인해 줘."

6. 기능을 더할 때 구조를 어떻게 쓸까?
나만 쓰는 스케줄러는 쓰다 보면 기능이 늘어납니다. 과제 마감일, 업무 우선순위, 개인 약속만 따로 보기 같은 것들입니다. 우선순위 하나만 더해도 보통 여러 곳이 함께 바뀝니다.
| 바뀌는 곳 | 바꾸는 내용 |
|---|---|
| types/schedule.ts | 일정 모양에 우선순위 항목 추가 |
| components/ScheduleForm.tsx | 우선순위를 고르는 입력칸 추가 |
| lib/schedules.ts | 우선순위 저장·불러오기 |
| components/ScheduleItem.tsx | 일정 줄에 우선순위 표시 |
| 데이터베이스 | 우선순위를 담을 칸 추가 |
그래서 "우선순위 추가해 줘"보다 이렇게 묻는 편이 안전합니다.
"일정에 우선순위를 추가하고 싶어. 자료 모양, 입력 화면, 저장 코드, 일정 표시 중 어디를 바꿔야 하는지 먼저 설명해 줘. 기존 기능에 미치는 영향도 알려 줘."
7. 내 프로젝트는 AI에게 어떻게 물어볼까?
이 글의 예시와 내 프로젝트는 이름이나 구성이 다를 수 있으니, 실제 파일을 기준으로 설명받는 것이 좋습니다. 아래 세 질문을 순서대로 써 보세요.
"이 프로젝트의 주요 폴더와 파일을 표로 보여 주고, 각각 무슨 역할인지 한 줄씩 설명해 줘. 나는 개발 초보야."
"오늘 화면 파일의 실제 코드를 짧게 나눠 보여 주고, 각 부분 바로 아래에 쉬운 설명을 붙여 줘. 코드는 고치지 마."
"완료 표시를 누르면 어떤 파일의 어떤 함수가 실행되는지 순서대로 알려 줘. 화면만 바꾸는 부분과 데이터베이스에 저장하는 부분을 구분해 줘."
AI가 파일 이름이나 함수 이름을 틀리게 말하기도 합니다. 설명을 들은 뒤에는 실제 파일을 열어 같은 이름이 있는지 확인하세요. 저도 새 프로젝트를 받으면 구조 설명부터 듣고, 실제 파일과 맞춰 봅니다.
정리
- AI가 만든 코드는 한 줄씩 읽기 전에 폴더 역할부터 봅니다. app은 화면, components는 부품, lib는 연결·저장 같은 공통 기능, types는 자료 모양입니다.
- 기획서의 저장할 정보는 types의 자료 모양이 됩니다. 날짜가 실제로 맞는지는 따로 검사해야 합니다.
- 화면 파일은 위쪽 준비, 가운데 기억과 동작, 아래쪽 화면 그리기로 나눠 읽습니다.
- 저장(toggleDone)과 화면 갱신(setSchedules)은 다른 일입니다. 어느 쪽이 빠졌는지에 따라 증상이 다릅니다.
- 내 일정만 다루게 하는 접근 규칙은 로그인과 별도로 설정해야 합니다.
원팩에서 만드는 업무 시스템 FROX는 화면과 파일이 훨씬 많지만, 화면·부품·데이터 처리를 나누는 기본 원리는 같습니다. 그래서 기능을 고칠 때도 먼저 "어느 폴더, 어느 칸인가"부터 찾습니다.
다음 글(5편): 3편의 기획서와 이 글의 구조를 AI에게 건네고, 「오늘」과 「이번 주」 화면을 내 PC에서 띄워 봅니다. 예시 일정을 넣어 화면과 버튼의 동작부터 확인합니다.
출처 (2026-10-16 확인)
- Next.js 공식 문서, Project Structure
- Next.js 공식 문서, Layouts and Pages
- Next.js 공식 문서, Environment Variables
- Next.js 공식 문서, use client
- TypeScript Handbook, Everyday Types (Union Types)
- Supabase 공식 문서, Row Level Security
함께 읽으면 좋은 글: 나만의 스케줄러 만들기 1편: 웹앱은 어떤 언어로 만들까? · 나만의 스케줄러 만들기 3편: 웹앱 기획서 쓰는 법

프로그램 기획자로 일하다, 2년 동안 하루 5~12시간씩 AI와 일하며 개발자가 됐습니다. 지금은 원팩에서 AI가 결합된 업무 시스템 FROX를 만듭니다.
