Project Structure

저장소는 backend와 frontend로 나뉩니다. 이 페이지는 프론트엔드 폴더를 중심으로 설명합니다.

Repository

meerkit/
├── backend/             FastAPI 백엔드
├── frontend/            Next.js 프론트엔드
├── docs/                설계·가이드 문서
├── .github/workflows/   CI
├── docker-compose.yml   로컬 DB
└── README.md

Frontend

frontend/src/
├── app/                 라우트 (연결 파일만)
│   ├── (meerkit)/       킷 화면: /me, /admin/members, /docs(문서 사이트용)
│   └── (service)/       서비스 화면 자리
├── components/ui/       shadcn 컴포넌트
├── lib/utils.ts         cn()
└── meerkit/             킷 본체 (수정하지 않는다)
    ├── api/             client.ts, auth.ts, users.ts
    ├── auth/            스토어, 훅, 가드, 폼, 모달
    ├── admin/           멤버 테이블, 역할 선택
    ├── docs/            이 문서 사이트
    ├── providers/       MeerkitProvider
    ├── welcome/         웰컴 페이지
    ├── styles/          tokens.css
    ├── config.ts  roles.ts  types.ts  index.ts

Project root

frontend/
├── meerkit.config.ts    내가 고치는 Meerkit 설정 (theme, motion, signup 옵션)
├── components.json     shadcn 설정
├── .env.example        환경 변수
└── src/

킷 폴더(src/meerkit)는 업데이트 대상이므로 건드리지 않고, 바꾸고 싶은 것은 meerkit.config.ts와 globals.css에서 합니다.

Where does X go?

Backend

backend/
├── alembic/             마이그레이션
├── tests/
└── app/
    ├── main.py          앱 생성
    ├── core/            설정, DB 연결
    ├── auth/            회원가입·로그인 (구현 예정)
    ├── llm/             LLM 호출 모듈 (구현 예정)
    └── features/        서비스 (서비스 코드는 여기에)

Import direction

코드가 서로를 가져오는 방향은 한쪽으로만 흐르게 합니다. 이렇게 해야 킷을 업데이트해도 내 서비스 코드가 깨지지 않습니다.

app/(service)/   내 서비스 화면
      │  가져다 쓴다 (@/meerkit)
      ▼
src/meerkit/     킷 본체          ← 서비스를 import하지 않는다
      │
      ▼
components/ui/   shadcn 컴포넌트

Rules

• meerkit/은 킷 코드입니다. 킷을 받아 쓰는 사람은 이 폴더를 수정하지 않는 것을 권장합니다.
• app/에는 한 줄짜리 연결 파일만 둡니다. 화면 본체는 @/meerkit에서 가져옵니다.
• 킷은 app/(service)/를 import하지 않습니다. 의존은 서비스 → 킷 방향으로만 흐릅니다.
• 서버 데이터는 TanStack Query, 토큰과 모달 상태는 Zustand에 둡니다.
• 스타일은 Tailwind utility와 토큰만 사용합니다.