What

주도(Zudo)는 기숙사 생활 전체를 하나의 플랫폼으로 통합한 웹 서비스다. 출결, 외박, 상벌점, 방과후 수강 신청, 건강 기록, 일일보고서까지 기숙사 운영에 필요한 모든 행정과 소통을 실시간으로 연결한다. Next.js App Router와 Supabase를 기반으로 구축했으며, 2026년 3월부터 경기북과학고등학교에서 정식 도입하여 매일 실사용 중이다.

Why

기존 기숙사 관리는 종이 출석부, 엑셀, 카카오톡 단체방이 혼재되어 있었다. 단순히 불편한 수준이 아니라, 이 비효율이 학생 안전 관리의 사각지대로 이어졌다. 사감 교대 시 인수인계가 누락되고, 학생 위치를 파악하는 데 시간이 걸리며, 학부모는 자녀의 귀사 여부를 실시간으로 알 수 없었다.

주도는 이 정보 비대칭을 제거하고, 기숙사 학생의 안전 관리 체계를 근본적으로 개선하기 위해 시작됐다.

How

사감, 사감장, 점호 담당, 교사, 학생, 학부모 6가지 역할이 하나의 플랫폼에서 실시간으로 연결된다. QR + TOTP 이중 인증으로 학생 출입을 자동 기록하고, 7가지 출결 뷰(위치별, 학생별, 2D 공간, 칸반, 캘린더, 갤러리, 분석)로 같은 데이터를 역할에 맞게 시각화한다.

학생은 모바일(/m)에서 출입·연장학습·상벌점을 확인하고, 학부모는 전용 포털(/p)에서 자녀의 귀사 여부를 실시간으로 본다. 방과후 수강 신청은 시나리오 기반 시뮬레이션으로 최적 배정한다.

185개 이상의 PostgreSQL 마이그레이션, 180개 이상의 커스텀 React 훅, Supabase Realtime 기반 실시간 동기화로 구성된 대규모 프로덕션 서비스다.

Impact

가장 예상치 못한 변화는 교사들이었다. 원래 사감 중심으로 설계했지만, 도입 후 교사들이 퇴근 후에도 학생 데이터를 적극 활용하기 시작했다. 출결 패턴으로 결석을 감지하고, 상벌점 추이로 행동 변화를 추적하며, 일일보고서로 기숙사 상황을 파악한다. "교사가 학교에 없어도 학생을 돌볼 수 있는 시스템"이 현장에서 가장 크게 체감하는 가치다.

학부모에게는 "열어보면 알 수 있는 시스템"이다. 전화하지 않아도 자녀의 귀사 여부를 실시간으로 확인할 수 있다. 학생에게는 "내 기숙사 생활이 내 손 안에 있다"는 자율성과 투명성이다.

아키텍처

Tech Stack

• Frontend: Next.js 16 (App Router), React 19, TypeScript 5
• Styling: Tailwind CSS 4, Radix UI (shadcn/ui)
• Backend: Supabase (PostgreSQL 17 + Auth + Realtime + Storage)
• State: Zustand (클라이언트), TanStack Query (서버 상태)
• Infra: Vercel (배포), Supabase Cloud (DB)

Architecture Decisions

Supabase를 선택한 이유는 PostgreSQL RLS로 DB 레벨 보안을 구현할 수 있었기 때문이다. 기숙사 관리 시스템에서 권한 체계는 생명줄이고, 프론트엔드가 아무리 조작되어도 데이터를 보호할 수 있어야 했다.

Next.js App Router는 서버 컴포넌트로 초기 로딩을 빠르게 하면서도 Supabase Realtime과 클라이언트 상태를 자연스럽게 결합할 수 있었다. TanStack Query로 서버 상태를 캐싱하고, Zustand로 UI 상태(모달, 선택, 필터)를 관리하는 하이브리드 패턴을 사용했다.

Data Flow

컴포넌트 → TanStack Query 훅 → Supabase RPC/REST. Supabase Realtime 구독으로 출결·외박·상벌점 변경이 즉시 반영된다. 오프라인 상황에서도 TanStack Query의 큐잉과 지수 백오프 재시도로 데이터 유실을 방지한다.

Decision 1: 8단계 역할 계층 + RLS 전면 적용

Context: 기숙사에는 사감장, 사감, 점호 담당, 교사, 학생, 학부모 등 역할이 많고, 각각 접근할 수 있는 데이터가 다르다. IT에 익숙하지 않은 선생님들이 쓰는 시스템이라 프론트엔드 검증만으로는 부족했다. Decision: RLS를 전면 적용하고, 8단계 역할 계층을 DB 레벨에서 강제했다. Consequence: 프론트엔드 코드가 조작되어도 권한 밖 데이터에 접근 불가. 단, RLS 자기재귀 함정을 SECURITY DEFINER 함수로 해결해야 했다.

Decision 2: 7가지 출결 뷰

Context: 사감은 "지금 이 방에 누가 없지?"가 중요하고, 교사는 "이 학생의 출결 패턴이 어떤지?"가 중요하다. 하나의 뷰로는 둘 다 만족시킬 수 없었다. Decision: 동일한 출결 데이터를 위치별, 학생별, 2D 공간, 칸반, 캘린더, 갤러리, 분석 차트 7가지로 시각화했다. Consequence: 사감은 공간 뷰로 빈 자리를 한눈에 파악하고, 교사는 캘린더/분석 뷰로 결석 패턴을 추적한다.

Decision 3: QR + TOTP 이중 인증 출입

Context: 학생 출입 기록을 자동화하되, 대리 출석이나 QR 도용을 방지해야 했다. Decision: 물리 QR 스캐너와 TOTP 이중 인증을 결합. 자동 벌점 규칙으로 지각·무단 외출을 자동 처리. Consequence: 사감의 수동 확인 부담이 크게 줄었고, 규칙 적용의 일관성이 높아졌다.

Decision 4: 3개 모바일 도메인 분리

Context: 반응형 디자인만으로는 학생, 학부모, 점호 담당의 완전히 다른 사용 동선을 커버할 수 없었다. Decision: /m(학생), /p(학부모), /rc(점호)를 독립 도메인으로 분리했다. Consequence: 역할별로 최적화된 UX를 제공하고, iOS ITP 대응 같은 플랫폼 특화 처리도 독립적으로 가능해졌다.

배운 점

종이에서 디지털로 전환할 때 핵심은 "덜 귀찮게"다. 기존보다 한 단계라도 더 귀찮으면 현장에서 안 쓴다. 클릭 수를 줄이는 게 기능 추가보다 중요하다는 걸 IT에 익숙하지 않은 선생님들과 일하며 체감했다.

처음에는 사감 중심으로 설계했지만, 도입 후 교사들이 적극적으로 활용하기 시작했다. 사용자 범위를 넓게 잡는 것이 제품의 가치를 키운다는 교훈이다.

RLS 자기재귀 문제를 초기에 SECURITY DEFINER 패턴으로 확립한 건 좋은 판단이었다. 역할이 추가될 때마다 전체 정책을 재검토해야 하므로, 권한 체계는 처음부터 세밀하게 설계해야 한다.

실패한 시도

방과후 모듈 초기 설계에서 출석 위치를 학습실이 아닌 원래 교실 기준으로 추적하는 구조적 결함이 있었다. 개별 기능은 동작했지만, 전체 파이프라인을 관통하는 통합 테스트가 없어서 배포 후에야 문제를 발견했다. 복잡한 비즈니스 로직은 단위 테스트만으로 부족하다.

DB에서 반환하는 RPC의 필드명(camelCase)과 프론트엔드 기대값(snake_case)이 달라 기능 전체가 깨진 적도 있다. 경계면의 타입 불일치는 런타임에서야 드러나기 때문에 TypeScript 타입 생성 자동화가 필수다.

185개 마이그레이션이 쌓이면서 로컬 환경 세팅과 온보딩 시간이 늘어났다. 다시 한다면 초기 스키마 설계에 더 시간을 투자했을 것이다.

타임라인

시기	마일스톤
2025.10	프로젝트 시작 — 출결·외박 핵심 기능 개발. Next.js + Supabase 기반 아키텍처 확정
2025.11	관리자 패널, 상벌점 시스템, QR 스캐너 연동. 8단계 RBAC + RLS 설계
2025.12	방과후 관리, 일일보고서, 건강 기록, 채팅 시스템 구축
2026.01	학부모 포털(/p), 모바일 최적화(/m, /rc), 보안 강화 (RLS 전면 적용)
2026.02	방과후 수강 최적화 엔진, 시설 보수, 점호 전용 뷰. 방과후 모듈 전면 재설계
2026.03	경기북과학고등학교 정식 도입 — 실사용 시작
2026.04	현장 피드백 기반 지속 개선. 교사들의 적극적 활용 확인. 추가 학교 확장 + SaaS화 검토 중