[타임시트] 스택과 구조 안내 (00)

타임시트는 파트타임 근무자의 출퇴근과 급여를 관리하는 웹 앱이다. 사장(마스터)이 매장을 만들고 초대 코드로 알바생(멤버)을 부르면, 알바생은 휴대폰 브라우저로 출퇴근을 찍고 급여를 본다. 2026-09-25 하루 동안 만들어 웹과 API 두 서버로 운영에 올렸다.

이 시리즈는 기능이 아니라 스택을 기준으로 나눈다. 편마다 그 스택이 이 프로젝트에서 무슨 일을 맡았는지, 왜 골랐는지, 코드가 어떻게 생겼는지, 어디서 막혔고 어떻게 고쳤는지를 적는다. 막힌 곳은 저장소 작업 히스토리에 남은 실패 기록에서 가져온다.

1. 스택 한 장

버전은 node_modules 에 실제로 설치된 값이다. package.json 에 적힌 범위(^5.1.0 같은)와 다를 수 있다.

표 1. 시리즈가 다루는 스택

Neon 쪽 Postgres 버전은 확인하지 못했다. 로컬은 Docker 의 postgres:18.6-alpine 이다.

2. 요청이 흘러가는 길

브라우저는 웹 주소 하나만 안다. API 주소는 따로 있지만 브라우저가 직접 부르지 않는다.

표 2. 요청 하나가 지나가는 길

rewrites 는 웹 서버가 받은 요청을 다른 주소로 대신 보내 주는 설정이다. 이렇게 하면 브라우저 입장에서 화면과 API 가 같은 출처(스킴·호스트·포트가 같은 주소)가 된다. 로그인 쿠키를 SameSite=Strict 로 걸어도 제대로 실리는 이유가 이것이다.

// web/next.config.ts
const API_URL = process.env.API_URL ?? "http://localhost:4200";

const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: "/api/:path*", destination: `${API_URL}/api/:path*` }];
  },
};

API 계약은 한 방향으로만 흐른다. 서버의 zod 스키마가 원본이고, 웹은 거기서 생성된 타입만 본다.

표 3. 계약이 흘러가는 순서

서버가 스키마를 바꾸고 2·3번을 다시 돌리면 웹의 타입 검사가 깨지는 자리가 생긴다. 그 자리가 웹에서 고칠 곳이다. 생성된 schema.d.ts 는 손으로 고치지 않는다.

3. 차례

표 4. 시리즈 목차

4. 저장소 구조

timesheet/
├── server/          Express API (timesheet-server)
│   ├── src/         contract.ts, app.ts, auth/, stores/, shifts/, requests/
│   └── prisma/      schema.prisma, migrations/
├── web/             Next.js (timesheet-web)
│   └── src/         app/, components/, auth/, api/, lib/
└── docs/            prd/, api/openapi.json, history/, verify/

급여 계산은 web/src/lib/pay.ts 한 곳에만 있다. 서버는 근무 기록과 멤버별 조건만 내려 주고 금액은 웹이 계산한다.

다음 편: [타임시트] Next.js 16 App Router — 같은 출처 쿠키와 정적 화면 (01)