ssuAI

한국어 · English

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

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

플랫폼에서 맡는 역할

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

Related MCP server: ku-portal-mcp

제품 흐름

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

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

아키텍처

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

엔지니어링 근거

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

로컬 실행과 검증

Node.js 20과 pnpm 9를 사용한다. 로컬 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

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

문서

• 문서 지도

• 제품 범위

• 프론트엔드 아키텍처

• 보안 경계

• ADR 목록

• ssuMCP의 MCP 도구 계약

범위와 제약

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

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

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

라이선스

MIT