시작하기
Neul 프로젝트 개요와 v5 모노레포 아키텍처 한눈에 보기
이 문서는 Neul 프로젝트에 새로 합류한 개발자를 위한 온보딩 가이드입니다. 로컬 환경 구성부터 아키텍처, 배포, 테스트, 그리고 이 저장소에서 Claude Code 를 활용하는 방법까지를 다룹니다.
Neul 이란
Neul 은 학생의 하루(아침 체크인 · 회고 · 인사이트)를 함께 돌보는 서비스입니다. 웹과 모바일(iOS/Android)에서 동일한 화면을 제공하며, 백엔드는 Cloudflare 엣지에서 동작합니다.
이 문서의 정확성
여기 적힌 명령·구조·결정은 저장소 루트의 AGENTS.md(= CLAUDE.md 가 import)
를 원본으로 삼아 정리했습니다. 세부 구현이 바뀌면 AGENTS.md 가 먼저
갱신되고, 이 문서가 뒤따릅니다.
v5 스택
저장소는 Next.js 단일 앱에서 Turborepo 모노레포로 마이그레이션되었습니다.
| 레이어 | 기술 |
|---|---|
| 웹/모바일 | React + Vite SPA + Capacitor(iOS/Android), Tailwind v4, motion |
| API | Hono on Cloudflare Workers (@cloudflare/vite-plugin dev, wrangler deploy) |
| DB | Drizzle ORM(pg-core) + postgres-js + Supabase Postgres |
| 공용 로직 | 프론트·백 공용 순수 로직/타입(zod 스키마, 채팅 시나리오, 인사이트 수식) |
설치된 패키지 버전이 학습 데이터보다 새로울 수 있습니다. SDK/프레임워크 코드를
쓰기 전에는 node_modules 의 실제 .d.ts/README 를 먼저 확인하세요(특히 hono,
drizzle-orm, @cloudflare/vite-plugin, jose, @microsoft/fetch-event-source,
@tailwindcss/vite).
모노레포 구조
neul/
├─ apps/
│ ├─ web # React + Vite SPA + Capacitor (ios/, android/, capacitor.config.ts)
│ ├─ api # Hono on Cloudflare Workers
│ └─ docs # 이 문서 사이트 (fumadocs / Next.js App Router, 정적 export)
├─ packages/
│ ├─ db # Drizzle 스키마 + postgres-js 클라이언트 + 마이그레이션 + seed/presets
│ └─ shared # 프론트·백 공용 순수 로직/타입
├─ e2e-web/ # Playwright e2e 스펙
├─ e2e-native/ # Appium(WebdriverIO) 네이티브 e2e
├─ turbo.json
└─ pnpm-workspace.yaml # apps/* , packages/*- 패키지 이름 규칙은
@neul/<name>입니다(@neul/web,@neul/api,@neul/db,@neul/shared, 그리고 이 문서는@neul/docs). - pnpm 워크스페이스 글롭은
apps/*와packages/*입니다.