ssuAI

한국어 · English

공개 캠퍼스 정보, 개인 학사·LMS·도서관 데이터, 승인 기반 AI 작업을 하나의 웹 경험으로 연결한 Next.js 애플리케이션이다. 브라우저에 비밀 값을 노출하지 않으면서 대시보드와 SSE 챗봇을 제공한다.

라이브 앱 · 챗봇 · 플랫폼 사례 연구 · 문서 지도

플랫폼에서 맡는 역할

이 저장소는 프론트엔드와 BFF 경계만 소유한다. 학교 시스템 연동과 데이터 정합성은 ssuMCP, 자연어 라우팅과 대화 checkpoint는 ssuAgent의 책임이다.

Related MCP server: studieplus-mcp

제품 흐름

홈, 학사, 도서관, 캠퍼스, 챗봇은 데스크톱 사이드바와 모바일 하단 탐색을 공유한다. 디자인 결정과 접근성 기준은 UI redesign ADR에 기록했다.

웹과 모바일을 한 코드베이스로 만드는 방식

별도 네이티브 앱을 두지 않고 하나의 Next.js 반응형 웹을 사용한다. AppShell은 Tailwind의 lg 분기에서 데스크톱의 246px 고정 사이드바를 모바일의 상단 바와 5개 하단 탭으로 바꾸고, 하단 탭에는 safe-area-inset-bottom을 적용한다. 같은 데이터와 상태 로직을 공유하면서 홈 위젯은 3열에서 1열로, 주간 시간표는 월–금 5열에서 오늘 우선 목록으로 표현만 전환한다.

모바일 브라우저에서는 device-width, dvh 기반 채팅 높이와 16px 입력창을 사용한다. 핀치 줌을 막지 않으면서 iOS 입력 포커스의 자동 확대를 피하는 방식이다. 따라서 데스크톱과 모바일은 배포물도 하나이고, 화면 폭에 따른 탐색·배치만 달라진다.

챗봇에서 LMS 강의자료 일괄 받기

자연어 요청을 받은 ssuAgent가 LMS 도메인으로 전환해 인증과 학기 목록을 확인하고, ssuMCP의 비동기 내보내기를 시작한다. 준비된 제한 링크는 채팅 안에서 다운로드 버튼으로만 렌더링하며, 허용된 origin과 path를 통과하지 못한 링크는 일반 텍스트로 남긴다.

실명과 개인 학사·재정·대출·좌석 값은 공개 이미지에서 비식별화했다.

아키텍처

공개 GET/SSE는 선택적으로 backend origin을 직접 호출해 Vercel 함수 hop을 줄인다. 쿠키·Bearer·API key가 필요한 요청과 /api/agent/*는 항상 same-origin 서버 경로를 통과한다. 이 분리는 public CORS를 인증 surface로 확장하지 않으면서도 공개 데이터의 지연을 줄인다. 상세 흐름은 프론트엔드 아키텍처에 있다.

엔지니어링 근거

주요 스택은 Next.js 16.2.12, React 19, TypeScript 6, TanStack Query, Tailwind CSS, Radix UI, Vitest, Testing Library, Playwright, axe-core와 Vercel이다.

로컬 실행과 검증

Node.js 20과 pnpm 10을 사용한다. 로컬 backend 없이 공개 ssuMCP를 대상으로 실행할 수도 있다.

git clone https://github.com/ghdtjdwn/ssuAI.git
cd ssuAI
cp .env.example .env.local
pnpm install --frozen-lockfile
pnpm dev

로컬 ssuMCP 없이 공개 backend를 사용할 때는 .env.local의 active localhost 값을 다음처럼 바꾼다.

NEXT_PUBLIC_SSUAI_API_BASE=https://ssumcp.duckdns.org
NEXT_PUBLIC_BACKEND_ORIGIN=https://ssumcp.duckdns.org

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm exec playwright install chromium
pnpm test:e2e

test:e2e는 데스크톱과 모바일 Chromium에서 핵심 5개 화면의 탐색 가능성, browser/React pageerror 0건, WCAG 2.0/2.1 A·AA 중 critical/serious axe 위반, 홈 화면의 실험실 LCP 2.5초·CLS 0.1 예산을 검사한다. 학교 API 요청은 503 fixture로 차단하므로 실제 학생 데이터나 외부 시스템 상태를 건드리지 않는다. 검증 서버는 기본적으로 새로 기동하며, 의도적으로 실행 중인 ssuAI 서버를 검사할 때만 E2E_REUSE_SERVER=true를 설정한다. 실패 시 trace·화면·Web Vitals JSON이 test artifact로 남는다.

이 검증은 로컬 production build의 회귀 게이트이지 실사용자 네트워크의 현장 RUM, 인증 여정 또는 학교 시스템 가용성의 증거가 아니다. 서비스별 실험 조건과 운영 주장 한계는 docs/portfolio-verification-boundary.md에 기록했다. 2026-07-27에 Next.js 16.2.12와 전이 의존성 패치 버전을 고정하고 확인한 pnpm audit --prod 0건도 당시 registry advisory 스냅샷이며 런타임 침투 테스트를 뜻하지 않는다.

환경 변수와 server-only/public 구분은 .env.example에 있다. 운영 proxy target과 secret 변경은 Vercel 설정과 함께 검증해야 하며, localhost 기본값으로 운영 구성을 추정하지 않는다.

문서

• 문서 지도

• 제품 범위

• 프론트엔드 아키텍처

• 보안 경계

• 실제 장애와 재발 방지 기록

• 검증 범위와 주장 한계

• ADR 목록

• ssuMCP의 MCP 도구 계약

범위와 제약

• 숭실대학교 공식 서비스가 아니며, 외부 학교 시스템의 가용성을 보장하지 않는다.

• 개인 화면과 상태 변경은 유효한 학교 계정 및 provider 연결이 필요하다.

• CI는 코드의 빌드·테스트를 검증하며 Vercel 환경 변수나 외부 서비스의 종단 동작까지 증명하지 않는다.

라이선스

MIT