Introduction
Meerkit이 무엇이고 무엇을 제공하는지 소개합니다.
Meerkit은 회원가입, 로그인, 역할 기반 권한, 유저 관리 화면을 미리 갖춘 AI 서비스 스타터킷입니다. 새 프로젝트마다 인증을 다시 만들지 않고, 명령어 한 줄로 동작하는 기반 위에서 서비스 기능만 얹을 수 있습니다.
Meerkit은 컴포넌트 라이브러리가 아니라 템플릿입니다. 코드는 전부 프로젝트 안에 복사되므로 받아서 마음대로 고칠 수 있습니다.
Principles
- Ready to run: 설치 후 바로 가입·로그인·비밀번호 재설정·관리자 기능을 테스트할 수 있습니다.
- Open code: 모든 화면과 훅이
src/meerkit/안에 그대로 있습니다. - Separated: 킷 코드와 서비스 코드를 폴더로 분리해, 업데이트와 커스터마이징이 서로 방해하지 않습니다.
- Server-verified: 화면에서 버튼을 숨기는 것은 편의일 뿐이고, 권한 검증은 항상 백엔드가 합니다.
- Themeable: 색, 반경, 폰트를 토큰 한 파일에서 바꿉니다.
What's included
| 영역 | 포함된 것 |
|---|---|
| 프론트엔드 | Next.js(App Router), shadcn/ui, Tailwind, Zustand, TanStack Query |
| 백엔드 | FastAPI, PostgreSQL, Alembic, JWT 인증 |
| 인증 | 회원가입, 로그인, 로그아웃, 토큰 자동 갱신 |
| 계정 보호 | 연속 로그인 실패 잠금(횟수·시간 설정 가능), 비밀번호 찾기·재설정, 비밀번호 변경 |
| 가입 | 약관 동의(체크박스), 선택 항목(닉네임·주소·성별 등), 비밀번호 확인, 이메일 인증(선택) |
| 입력 부품 | 주소 검색(2가지 방식), 첨부파일 드래그앤드롭, 체크박스, 라디오, 페이지네이션 |
| 권한 | MASTER / OWNER / VIEWER / WRITER 역할과 라우트 가드 |
| 관리자 | 멤버 검색·필터·페이지네이션, 역할 변경, 탈퇴 처리 |
| 환경 | docker-compose 로컬 DB, 설정 스크립트, CI |
Tech stack
| 구분 | 기술 | 용도 |
|---|---|---|
| UI | Next.js, React, shadcn/ui, Tailwind v4 | 화면과 컴포넌트 |
| 클라이언트 상태 | Zustand | 액세스 토큰, 모달 열림 상태 |
| 서버 상태 | TanStack Query | 내 정보, 멤버 목록 캐시 |
| HTTP | Axios | 토큰 부착, 401 시 자동 갱신 |
| API | FastAPI | 인증·유저 API |
| DB | PostgreSQL | users, roles 테이블 |
Who is it for
- 가입·로그인·권한 관리를 매번 새로 만들고 싶지 않은 팀
- AI 서비스 같은 기능 개발에 시간을 쓰고 싶고, 사용자 관리는 검증된 기반 위에서 시작하고 싶은 팀
- shadcn/ui와 Tailwind를 이미 쓰고 있어서, 그 방식 그대로 인증 화면을 얹고 싶은 팀
What users can do
킷으로 만든 서비스를 쓰는 사람은 역할에 따라 다음을 할 수 있습니다.
| 누가 | 할 수 있는 것 |
|---|---|
| 방문자 | 웰컴 페이지에서 회원가입, 로그인 |
| 방문자 | 비밀번호를 잊었을 때 이메일로 재설정 링크 받기 |
| 로그인한 모든 사용자 | 아바타 메뉴 열기, 내 정보·비밀번호 수정, 로그아웃 |
| MASTER (관리자) | 멤버 검색·필터·페이지 이동, 확인 창에서 역할 부여·변경, 탈퇴 처리 |
| OWNER · WRITER · VIEWER | 역할에 맞는 서비스 기능 사용 (내 서비스에서 가드로 구현) |
How the pieces connect
브라우저 (Next.js 화면) │ 회원가입 · 로그인 · 관리자 화면 (src/meerkit) ▼ /api 프록시 ── 같은 도메인처럼 동작, 쿠키·CORS 단순화 ▼ FastAPI 백엔드 ── 토큰 발급, 권한 검증 (서버가 최종 판단) ▼ PostgreSQL ── users, roles
What is not included
범위를 좁게 유지하기 위해 다음은 기본 제공하지 않습니다. 필요하면 서비스에서 추가하세요.
- 링크 방식 이메일 인증, 소셜 로그인, 2단계 인증
- 프로필 이미지 저장 API (고르고 미리 보는 화면 부품 ProfileImageField만 있고, 올린 파일의 저장은 서비스 서버가 맡습니다)
- 실제 약관 문구와 메일 발송 (샘플 약관 페이지만 있습니다)
- 세부 권한(permission) 테이블, 조직·팀 구조
- AI 사용량 기록과 한도 관리 (관리자용 사용량 화면 UI는 제공하며, 실제 집계는 추후 적용 예정)