SaaS Admin Dashboard — Starter

소규모 SaaS 서비스의 운영자 대시보드 풀스택 앱입니다.

프로젝트 구조

agent-eval-loop-starter/
├── api/          # Express + SQLite 백엔드
├── web/          # React + Vite 프론트엔드
├── evals/        # 평가 harness
└── package.json  # 워크스페이스 루트

셋업

사전 요구사항

• Node.js 20 이상
• npm 10 이상

설치 및 실행

# 1. 의존성 설치
npm install

# 2. 환경 변수 파일 생성
cp .env.example .env
# .env 파일을 열어 값을 채워 넣으세요.

# 3. 시드 데이터 생성
npm run seed

# 4. API 서버 실행 (api/ 디렉토리에서)
cd api && npm run dev

# 5. 웹 앱 실행 (별도 터미널, web/ 디렉토리에서)
cd web && npm run dev

기본적으로 API는 http://localhost:3001, 웹 앱은 http://localhost:5173에서 실행됩니다.

테스트

npm test

타입 검사 / 린트

npm run typecheck
npm run lint

시드 데이터 초기화

npm run reset && npm run seed

API 인증

모든 API 엔드포인트는 Authorization: Bearer <ADMIN_TOKEN> 헤더를 요구합니다.

ADMIN_TOKEN은 별도 발급 시스템이 아니라 서버와 클라이언트가 공유하는 단순 문자열(shared secret) 입니다. 서버가 알고 있는 값과 요청 헤더의 값이 문자열로 일치하면 통과합니다.

기본 동작

.env가 없어도 그대로 돕니다 — 코드 fallback이 dev-token이라, 개발·테스트 시 별도 셋업 없이 다음과 같이 호출할 수 있습니다:

curl -H "Authorization: Bearer dev-token" http://localhost:3001/api/users

web/ 프론트엔드(web/src/lib/api.ts)도 같은 dev-token을 자동으로 보내도록 셋업돼 있습니다.

다른 값으로 바꾸려면

.env.example을 .env로 복사한 뒤 ADMIN_TOKEN을 원하는 값으로 적습니다.

# .env
ADMIN_TOKEN=my-secret-value

이후 API 호출도 모두 그 값을 헤더로 보내야 합니다. 프론트엔드에서 다른 값을 쓰려면 web/.env에 VITE_ADMIN_TOKEN=<같은값>을 적습니다.

진짜 인증 시스템이 아닌 이유

이 starter는 의도적으로 인증을 작동만 하는 최소 형태로 둡니다 — 토큰 발급·세션·CSRF 같은 부분은 학습 범위 밖이라서요. 운영 환경에 그대로 쓰지 마세요.

기술 스택

• 백엔드: Express, better-sqlite3, TypeScript
• 프론트엔드: React, Vite, Tailwind CSS, shadcn/ui
• 테스트: vitest, @testing-library/react, supertest