동치미

Service · Team · Workspace · Tech Stack · Documents · Convention

Service

동네 마트의 할인 정보들을 모바일 전단으로 만들어 주민에게 전하는 서비스, 동치미!

엑셀을 활용해 할인 상품을 관리하며 오늘의 특가 상품을 빠르게 등록하고 공유할 수 있어요.
점주분들은 매장 안에만 머물던 할인 정보를 공유하고 주민분들은 내 주변 마트의 다양한 할인 상품 소식을 받아보고 공유할 수 있답니다!

무엇을 할 수 있나요?
[점주] 🥒행사 할인 상품 등록 및 확인
[점주] 🥦오늘의 특가 상품 등록 및 확인
[주민] 🍎모바일 웹으로 간편하게 전단 확인

Team

DONCHIMI Web Developers

장민수

박소이

이채원

한다경

이현종

Workspace

Surface	Role	Current State
apps/client	고객 웹, Next.js App Router	적용
apps/market-owner	사장님 웹, React SPA	적용
packages/design-system	직접 구현하는 디자인 시스템	기본 package 적용
packages/shared	공통 유틸, 타입, 상수	placeholder package 적용
packages/eslint-config	repo 공통 ESLint config	적용
packages/typescript-config	repo 공통 TypeScript config	적용
.github/workflows	GitHub Actions, PR 자동화	CI, E2E, 성능, 배포 알림 적용
.agents/skills	Codex agent workflow	repo-local skill 적용
docs, recipes, templates	구조, 컨벤션, 작업 절차, spec	문서 source of truth

flowchart LR
  subgraph "Apps"
    CLIENT["apps/client<br/>고객 웹"]
    OWNER["apps/market-owner<br/>사장님 웹"]
  end

  subgraph "Packages"
    DS["packages/design-system"]
    SHARED["packages/shared"]
    ESLINT["packages/eslint-config"]
    TSCONFIG["packages/typescript-config"]
  end

  subgraph "Workflow"
    AGENT["AGENTS.md"]
    SKILLS[".agents/skills"]
    DOCS["docs"]
    RECIPES["recipes"]
    TEMPLATES["templates"]
    GITHUB[".github"]
  end

  CLIENT --> DS
  CLIENT --> SHARED
  OWNER --> DS
  OWNER --> SHARED
  CLIENT --> ESLINT
  OWNER --> ESLINT
  CLIENT --> TSCONFIG
  OWNER --> TSCONFIG
  AGENT --> DOCS
  AGENT --> SKILLS
  SKILLS --> DOCS
  DOCS --> TEMPLATES
  RECIPES --> DOCS
  GITHUB --> DOCS

Loading

Tech Stack

Status는 현재 develop의 추적 파일과 팀 기술 결정 방향을 함께 반영합니다.

Core

Label	Category	Selection	Status	Why
	Language	TypeScript	적용	앱, package, config 전반에서 타입 안정성을 기본값으로 둡니다.
	Monorepo	pnpm + Turborepo	적용	workspace dependency, task cache, generator를 repo 단위로 관리합니다.
	고객 UI	Next.js App Router	적용	고객 웹은 라우팅, 빌드, 배포 최적화가 필요한 제품 앱입니다.
	사장님 UI	React SPA	적용	별도 제품 컨벤션이 없는 사장님 웹을 가볍고 명확하게 시작합니다.
	사장님 Route	React Router	적용	React SPA 안에서 명시적인 route config와 fallback route를 관리합니다.

Product Foundation

Label	Category	Selection	Status	Why
	Network	ky	적용	작은 API wrapper로 timeout, error normalization, JSON 응답을 통일합니다.
	Server State	TanStack Query	적용	서버 캐시, loading/error 상태, refetch 정책을 앱 표준으로 둡니다.
	Client State	Zustand	결정	전역 UI/client state가 필요할 때 작은 store 단위로 분리합니다.
	Form	React Hook Form	결정	form state와 validation 결합 비용을 줄입니다.
	Validation	Zod	결정	TypeScript와 함께 runtime schema와 form validation을 공유합니다.
	Styling	vanilla-extract	결정	디자인 시스템 적용을 위해 type-safe CSS와 정적 추출을 우선합니다.
	Design System	직접 구현	기본 적용	packages/design-system에서 공통 컴포넌트와 스타일 계약을 관리합니다.
	API Schema	openapi-typescript	후속	API contract가 안정되면 타입 생성으로 client drift를 줄입니다.

Quality, Delivery, Analytics

Label	Category	Selection	Status	Why
	Code Quality	ESLint, Prettier, Husky, lint-staged	적용	로컬과 CI에서 format, lint, typecheck를 같은 기준으로 실행합니다.
	Unit / Integration Test	Vitest, React Testing Library, MSW	적용	컴포넌트 동작, hook, API mock 검증을 위한 기본 조합입니다.
	E2E Test	Playwright	적용	앱 bootstrap smoke부터 브라우저 기반 회귀 검증까지 확장합니다.
	Component Docs	Storybook + Chromatic	적용	디자인 시스템과 shared component의 상태별 문서화를 담당합니다.
	Deploy	Vercel	적용	Next.js 최적화, preview deployment, GitHub 연동 자동 배포를 활용합니다.
	CI/CD	GitHub Actions + Vercel CD	적용	PR에서는 검증을, main merge 이후에는 배포 자동화를 담당합니다.
	Monitoring / Analytics	Sentry + Discord, Google Analytics 또는 Vercel Analytics, Amplitude	후속	오류 감지, 알림, 사용자 행동 분석은 제품 지표가 생긴 뒤 연결합니다.

Local Development

Runtime

Tool	Version Source
Node	.node-version
pnpm	package.json

Setup

pnpm install

App Ports

App	Command	Port	Note
고객 웹	pnpm dev:web	3000	Next.js dev server
사장님 웹	pnpm dev:market-owner	5173	Vite strict port

Verification

git diff --check
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build

문서만 변경한 경우 최소 검증은 아래 두 명령입니다.

git diff --check
pnpm format:check

Ground Rules

Rule	Standard
Work source	Jira는 작업 단위와 상태의 기준입니다.
Decision log	회의나 메신저 결정도 구현에 영향을 주면 Jira 또는 docs에 남깁니다.
Spec gate	새 page, form, API, shared component, 디자인시스템 컴포넌트는 spec 필요 여부를 먼저 판단합니다.
Communication	작업 공유는 오늘 진행, 막힌 점, 다음 action 중심으로 짧게 남깁니다.
Schedule	일정은 Jira board와 milestone 기준으로 관리하고, 리스크는 발견 시점에 공유합니다.
Convention	컨벤션 변경은 README보다 가까운 source of truth 문서에 먼저 반영합니다.

Documents

Area	Link
문서 인덱스	docs/index.md
저장소 구조	Repo Structure
앱 구조	App Structure
디자인 시스템	Design System
Package 관리	Package Management
로컬 개발	Local Development
CI	CI
테스트	Testing
Spec 작성	Spec Writing
Turbo Generator	Turbo Generators
Agent Guide	AGENTS.md
Agent Harness	Agent Harness
Agent Indexing	Agent Indexing
Jira 템플릿	Jira Issue Template
Decision Log	Decision Log Guide

Convention

Code

Target	Convention	Example
Folder	kebab-case	user-profile/
Component file	PascalCase	UserCard.tsx
Hook/API/Utils	kebab-case	use-auth.ts, auth-api.ts, format-date.ts
TanStack Query	kebab-case	use-user-query.ts, use-user-mutation.ts

• 컴포넌트는 arrow function으로 선언하고 일반 컴포넌트는 named export를 사용합니다.
• 의미 없는 wrapper div는 피하고 Fragment 또는 semantic tag를 우선합니다.
• var는 사용하지 않고, 재할당이 필요 없으면 const를 사용합니다.
• Boolean 값은 is prefix를 권장합니다.
• 타입 이름은 PascalCase, props 타입은 Props suffix를 사용합니다.
• 버튼, label, heading level, focus-visible, keyboard interaction을 접근성 기본값으로 봅니다.

자세한 기준: Coding Convention

Git / Jira / PR

Topic	Rule
Branch	prefix/{scope}/{JIRAKEY}-work-summary
Commit	prefix(scope): {JIRAKEY} work summary
PR	PREFIX(scope): {JIRAKEY} work summary 형태이며, 실제 제목에서는 PREFIX를 대괄호로 감쌉니다.
Jira	root/docs/CI/workflow는 DCMFE-*, client는 DCMCL-*, design-system package/web은 DCMDS-*

예시:

docs/root/DCMFE-24-readme-project-guide
docs(docs): DCMFE-24 README 프로젝트 소개 정리
[DOCS](docs): DCMFE-24 README 프로젝트 소개 정리

flowchart LR
  ISSUE["Jira issue"] --> BRANCH["Branch"]
  BRANCH --> SPEC["Spec 필요 여부 판단"]
  SPEC --> IMPLEMENT["Implementation"]
  IMPLEMENT --> VERIFY["Verification"]
  VERIFY --> PR["Pull Request"]
  PR --> REVIEW["Code Review"]

Loading

• 구현 전 Jira 이슈를 만들고, 구현 착수 시 진행 중 상태로 전환합니다.
• 변경 surface가 다르면 커밋을 분리합니다. 한 PR에서 리뷰하기 어려우면 Jira도 나눕니다.
• PR 본문은 Pull Request Template과 Pull Request Writing을 기준으로 작성합니다.
• 실제 실행한 검증만 PR과 최종 요약에 적고, 생략한 검증은 이유를 남깁니다.

자세한 기준: Git Convention, Jira Issue Authoring, PR Checklist