메인 콘텐츠로 건너뛰기
Sonamu 프로젝트는 모노레포 구조로 백엔드(api)와 프론트엔드(web)를 함께 관리합니다.

​
전체 구조

프로젝트 전체 구조

​
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 디렉토리 구조
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 디렉토리 구조
엔티티 파일 생성 과정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/ 디렉토리

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 디렉토리 구조
vite.config.ts
  • Vite 개발 서버 설정
  • TanStack Router, Tailwind CSS v4, unplugin-icons 플러그인
  • API 프록시 설정 (/api → http://localhost:34900)
  • SSR 설정 포함
tailwind.config.ts
  • Tailwind CSS v4 설정
.sonamu.env
  • API 서버 연결 정보
  • API_HOST, API_PORT 설정

​
src/ 디렉토리

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 엔티티를 생성하면 다음과 같은 구조가 만들어집니다:
user 폴더 구조 1user 폴더 구조 2

​
각 파일의 역할

{
  "properties": [
    {
      "name": "id",
      "type": "int",
      "isPrimary": true
    },
    {
      "name": "email",
      "type": "varchar"
    },
    {
      "name": "name",
      "type": "varchar"
    }
  ]
}
VS Code split view
자동 생성 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.jsonSonamu 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의 전체 개발 사이클을 이해하고 효율적으로 작업하는 방법을 배워보세요.