프로젝트 구조

Sonamu 프로젝트는 모노레포 구조로 백엔드(api)와 프론트엔드(web)를 함께 관리합니다.

전체 구조

📁myapp/ - Sonamu 모노레포 루트

📁node_modules/

📁packages/

📁api/ - 백엔드 API 서버

📁web/ - 프론트엔드 웹 애플리케이션

📄GITIGNORE.gitignore

📄YAMLpnpm-lock.yaml

📄YAMLpnpm-workspace.yaml - 워크스페이스 및 의존성 catalog

📄MDREADME.md - 프로젝트 문서

pnpm 워크스페이스

루트의 pnpm-workspace.yaml에서 패키지와 공통 의존성 버전을 관리합니다:

pnpm-workspace.yaml

packages:
  - packages/api
  - packages/web

catalog:
  "@tanstack/react-query": ^5.90.12
  "@tanstack/react-router": 1.143.11
  react: ^19.2.3
  vite: 7.3.0
  vitest: 4.0.16
  zod: ^4.1.12
  # ... 기타 공통 의존성

API 디렉토리 (백엔드)

루트 파일

📁packages/api/

📁src/ - 소스 코드

📁database/ - 데이터베이스 관련 파일

📄JSONpackage.json - 의존성 및 스크립트

📄TSvitest.config.ts - 테스트 설정

📄JSONtsconfig.json - TypeScript 설정

📄JSONtsconfig.schemas.json - 스키마 생성용 설정

📄JSONtsconfig.types.json - 타입 생성용 설정

📄TScustom-sequencer.ts - 테스트 시퀀서

📄SWCRC.swcrc - SWC 컴파일러 설정

📄ENV.env - 환경 변수 (자동 생성)

주요 파일 설명

package.json

백엔드 의존성 관리
npm 스크립트: dev, build, test, docker:up/down, dump, seed 등

vitest.config.ts

Vitest 테스트 설정
getSonamuTestConfig() 함수로 Sonamu 최적화 설정
커버리지, 리포터, 시퀀서 설정

tsconfig.json

메인 TypeScript 컴파일러 설정
tsconfig.schemas.json: Zod 스키마 생성 전용
tsconfig.types.json: 타입 정의 생성 전용

.env

데이터베이스 연결 정보 (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD)
프로젝트 설정 변수 (DATABASE_NAME, CONTAINER_NAME, PROJECT_NAME)
pnpm create sonamu 실행 시 자동 생성

src/ 디렉토리

📁packages/api/src/

📄TSindex.ts - 서버 진입점

📄TSsonamu.config.ts - Sonamu 설정 파일

📁application/ - 엔티티별 폴더 (자동 생성)

📁{entity}/

📄JSON{entity}.entity.json - 엔티티 정의

📄TS{entity}.model.ts - 비즈니스 로직

📄TS{entity}.types.ts - 타입 + Zod 스키마

📄TS{entity}.model.test.ts - 테스트 (선택)

📄TSsonamu.generated.ts - Base 스키마 (자동 생성)

📁i18n/ - 다국어 설정

📄TSko.ts - 한국어 번역

📄TSen.ts - 영어 번역

📁migrations/ - DB 마이그레이션 파일

📁testing/ - 테스트 설정

📄TSglobal.ts - 전역 테스트 설정

📄TSfixture.ts - Fixture 관리

📄TSsetup-mocks.ts - Mock 설정

📁typings/ - 타입 정의

📄TSsonamu.d.ts - Sonamu 전역 타입

📄TSfastify.d.ts - Fastify 확장 타입

📁utils/ - 유틸리티 함수

📄TSsubset-loaders.ts - Subset 로더

엔티티 파일 생성 과정application/{entity}/ 폴더 내의 파일들은 Sonamu UI를 통해 엔티티를 생성하고 스캐폴딩해야 생성됩니다:

.entity.json: Sonamu UI에서 엔티티 정의 시 자동 생성
.model.ts: pnpm scaffold model 또는 Sonamu UI의 Scaffolding 탭에서 생성
.types.ts: 엔티티 저장 시 자동 생성
.model.test.ts: pnpm scaffold model_test 또는 Sonamu UI의 Scaffolding 탭에서 생성 (선택사항)

처음 프로젝트를 생성했을 때는 application/ 폴더가 비어 있습니다. 첫 번째 엔티티를 생성하면 해당 폴더가 만들어집니다.

주요 디렉토리 설명

application/

첫 엔티티 생성 시 자동으로 생성됨
각 엔티티마다 별도 디렉토리 생성
예: User 엔티티 → application/user/ 디렉토리

application//.entity.json

엔티티 정의 파일
Sonamu UI에서 작성
데이터베이스 스키마의 소스

application//.model.ts

비즈니스 로직 구현
API 엔드포인트 정의 (@api 데코레이터)
직접 작성하는 파일

application//.types.ts

TypeScript 타입 정의
Zod validation 스키마
자동 생성되지만 확장 가능
프론트엔드와 공유

application/sonamu.generated.ts

모든 엔티티의 Base 스키마 자동 생성
Enum 타입 및 레이블 정의
직접 수정하지 말 것

i18n/

다국어 번역 파일
ko.ts: 한국어, en.ts: 영어
Entity 추가 시 sd.generated.ts가 자동 생성됨

migrations/

Sonamu UI에서 생성한 DB 마이그레이션 파일
pnpm sonamu migrate run으로 실행

testing/

Vitest 테스트 환경 설정
global.ts: export { setup } from "sonamu/test" 패턴 사용
Fixture 데이터 관리

더 알아보기 - 엔티티 파일

엔티티 정의하기 - entity.json 작성법
Model 만들기 - model.ts 작성 가이드
타입 시스템 - types.ts 이해하기
자동 생성되는 것들 - 어떤 파일이 자동 생성되는지
테스트 작성하기 - 테스트 파일 구조

database/ 디렉토리

📁packages/api/database/

📄YMLdocker-compose.yml - PostgreSQL 컨테이너 설정

📁fixtures/

📄SHinit.sh - 데이터베이스 초기화 스크립트

📁dumps/ - 데이터 덤프 파일

📁scripts/

📄SHdump.sh - 데이터 백업 스크립트

📄SHseed.sh - 데이터 복원 스크립트

주요 파일 설명

docker-compose.yml

PostgreSQL + pgvector 이미지
컨테이너 이름, 포트, 환경 변수 설정
pnpm docker:up으로 실행

fixtures/init.sh

데이터베이스 초기화 쉘 스크립트
pgvector 확장 설치 및 데이터베이스 생성
환경변수로 데이터베이스 이름 지정 (DATABASE_NAME, _fixture, _test)
pnpm create sonamu 실행 시 자동 생성

dumps/

pnpm dump 명령으로 생성된 SQL 파일
데이터 백업 저장소

scripts/

dump.sh: 현재 DB 데이터를 dumps/에 백업
seed.sh: dumps/의 데이터를 DB에 복원

더 알아보기 - 설정 파일

sonamu.config.ts 설정 - 프로젝트 전체 설정
데이터베이스 설정 - DB 연결 및 설정
서버 설정 - Fastify 서버 설정
TypeScript 설정 - 컴파일러 옵션
환경 변수 - .env 파일 관리

Web 디렉토리 (프론트엔드)

루트 파일

📁packages/web/

📁src/ - 소스 코드

📄HTMLindex.html - HTML 엔트리포인트

📄JSONpackage.json - 의존성 및 스크립트

📄TSvite.config.ts - Vite 설정

📄TStailwind.config.ts - Tailwind CSS 설정

📄JSONtsconfig.json - TypeScript 설정

📄JSONtsconfig.node.json - Node 환경 설정

📄ENV.sonamu.env - 환경 변수

주요 파일 설명

vite.config.ts

Vite 개발 서버 설정
TanStack Router, Tailwind CSS v4, unplugin-icons 플러그인
API 프록시 설정 (/api → http://localhost:1028)
SSR 설정 포함

tailwind.config.ts

Tailwind CSS v4 설정

.sonamu.env

API 서버 연결 정보
API_HOST, API_PORT 설정

src/ 디렉토리

📁packages/web/src/

📄TSXentry-client.tsx - 클라이언트 엔트리포인트

📄TSXentry-server.generated.tsx - SSR 엔트리포인트 (자동 생성)

📄TSXApp.tsx - 루트 컴포넌트

📄TSrouteTree.gen.ts - 라우트 트리 (자동 생성)

📁routes/ - TanStack Router 기반 페이지

📄TSX__root.tsx - 루트 레이아웃

📄TSXindex.tsx - 홈 페이지

📁services/ - API 서비스 (자동 생성)

📁{entity}/ - 엔티티별 서비스

📄TS{entity}.service.ts

📄TSsonamu.generated.ts

📄TSsonamu.shared.ts

📄TSservices.generated.ts

📁contexts/ - React Context

📄TSXSonamuContext.tsx - Sonamu Provider

📁i18n/ - 다국어 설정

📄TSko.ts

📄TSen.ts

📁admin-common/ - 공통 컴포넌트

📄TSXApiLogViewer.tsx

📁components/ - UI 컴포넌트

📁styles/ - 스타일 파일

📄TSvite-env.d.ts - Vite 타입 정의

주요 디렉토리 설명

routes/

TanStack Router 기반 파일 시스템 라우팅
__root.tsx: 전역 레이아웃
파일명이 URL 경로에 매핑됨

services/

API 서버와 통신하는 서비스 레이어
엔티티마다 자동 생성
TanStack Query 통합 지원

contexts/

React Context Provider
SonamuContext: 전역 상태 관리

i18n/

프론트엔드 다국어 번역 파일
API의 i18n과 동기화

admin-common/

재사용 가능한 공통 컴포넌트
ApiLogViewer 등 디버깅 도구

더 알아보기 - 프론트엔드

Service 작동 원리 - 자동 생성 메커니즘
Service 사용하기 - API 호출 방법
공유 타입 - 백엔드-프론트엔드 타입 동기화

엔티티 생성 시 파일 구조 예시

User 엔티티를 생성하면 다음과 같은 구조가 만들어집니다:

📁packages/api/src/application/

📁user/

📄JSONuser.entity.json - Sonamu UI에서 생성

📄TSuser.model.ts - 직접 작성

📄TSuser.types.ts - 자동 생성 (확장 가능)

📄TSuser.model.test.ts - 직접 작성 (선택)

📄TSsonamu.generated.ts - 자동 업데이트

📁packages/api/src/migrations/

📄SQL20250106120000_create_user.sql - 자동 생성

📁packages/web/src/services/

📁user/

📄TSuser.service.ts - 자동 생성

각 파일의 역할

{
  "properties": [
    {
      "name": "id",
      "type": "int",
      "isPrimary": true
    },
    {
      "name": "email",
      "type": "varchar"
    },
    {
      "name": "name",
      "type": "varchar"
    }
  ]
}

자동 생성 vs 직접 작성 - .entity.json: Sonamu UI에서 작성 - .model.ts: 직접 작성 - .types.ts: 자동 생성되지만 확장 가능 - sonamu.generated.ts: 자동 생성 - 수정 금지 - {entity}.service.ts: 자동 생성 - 수정 금지

더 알아보기 - 파일별 가이드

엔티티 정의하기 - entity.json 작성법
@api 데코레이터 - model.ts에서 API 정의
Entity Types - types.ts 활용하기
Generated Types - sonamu.generated.ts 이해

개발 시 주요 작업 위치

작업 내용	위치	방법
엔티티 정의	`packages/api/src/application/{entity}/{entity}.entity.json`	Sonamu UI
비즈니스 로직	`packages/api/src/application/{entity}/{entity}.model.ts`	직접 작성
커스텀 타입	`packages/api/src/application/{entity}/{entity}.types.ts`	직접 확장
API 엔드포인트	Model 파일에 `@api` 데코레이터	직접 작성
데이터베이스 설정	`packages/api/src/sonamu.config.ts`	직접 작성
서버 설정	`packages/api/src/sonamu.config.ts`	직접 작성
테스트 작성	`packages/api/src/application/{entity}/{entity}.model.test.ts`	직접 작성
페이지 컴포넌트	`packages/web/src/routes/`	직접 작성
공통 컴포넌트	`packages/web/src/admin-common/`	직접 작성

자동 생성 파일 주의사항 - sonamu.generated.ts: 절대 수정하지 마세요 - {entity}.service.ts: 절대 수정하지 마세요 - {entity}.types.ts: 확장은 가능하지만 자동 생성 부분은 수정하지 마세요

다음 단계

프로젝트 구조를 이해했다면, 이제 첫 번째 엔티티를 만들어보세요:

첫 엔티티 만들기

Sonamu UI를 사용하여 첫 번째 엔티티를 생성하고 데이터베이스 스키마를 정의하세요.

개발 워크플로우

Sonamu의 전체 개발 사이클을 이해하고 효율적으로 작업하는 방법을 배워보세요.

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문