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

​
전체 구조

📁my_app/ - Sonamu 모노레포 루트
📁api/ - 백엔드 API 서버
📁web/ - 프론트엔드 웹 애플리케이션
📄MDREADME.md - 프로젝트 문서

📸 필요: VS Code에서 열린 Sonamu 프로젝트 전체 디렉토리 구조 (Explorer 사이드바)

​
API 디렉토리 (백엔드)

​
루트 파일

📁api/
📁src/ - 소스 코드
📁database/ - 데이터베이스 관련 파일
📄JSONpackage.json - 의존성 및 스크립트
📄JSONtsconfig.json - TypeScript 설정
📄JSONtsconfig.schemas.json - 스키마 생성용 설정
📄JSONtsconfig.types.json - 타입 생성용 설정
📄TSvite.config.ts - Sonamu UI 빌드 설정
📄SWCRC.swcrc - SWC 컴파일러 설정
📄ENV.env - 환경 변수 (자동 생성)

📸 필요: api 디렉토리의 실제 파일 구조 (VS Code Explorer)

package.json
  • 백엔드 의존성 관리
  • npm 스크립트: dev, build, test, docker:up/down, dump, seed 등
tsconfig.json
  • 메인 TypeScript 컴파일러 설정
  • tsconfig.schemas.json: Zod 스키마 생성 전용
  • tsconfig.types.json: 타입 정의 생성 전용
vite.config.ts
  • Sonamu UI 개발 서버 설정 (pnpm sonamu ui)
  • HMR(Hot Module Replacement) 설정
.env
  • 데이터베이스 연결 정보
  • 프로젝트 설정 변수
  • pnpm create sonamu 실행 시 자동 생성

​
src/ 디렉토리

📁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 스키마 (자동 생성)
📁testing/ - 테스트 설정
📄TSglobal.ts - 전역 테스트 설정
📄TSfixture.ts - Fixture 관리
📁typings/ - 타입 정의
📄TSsonamu.d.ts - Sonamu 전역 타입
📄TSfastify.d.ts - Fastify 확장 타입
📁utils/ - 유틸리티 함수
📄TSsubset-loaders.ts - Subset 로더

📸 필요: api/src 디렉토리 구조 (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 타입 및 레이블 정의
  • 직접 수정하지 말 것
testing/
  • Vitest 테스트 환경 설정
  • Fixture 데이터 관리
  • 테스트 유틸리티
더 알아보기 - 엔티티 파일

​
database/ 디렉토리

📁api/database/
📄YMLdocker-compose.yml - PostgreSQL 컨테이너 설정
📁fixtures/
📄SQLinit.sql - 데이터베이스 초기화 SQL
📁dumps/ - 데이터 덤프 파일
📁scripts/
📄SHdump.sh - 데이터 백업 스크립트
📄SHseed.sh - 데이터 복원 스크립트
docker-compose.yml
  • PostgreSQL + pgvector 이미지
  • 컨테이너 이름, 포트, 환경 변수 설정
  • pnpm docker:up으로 실행
fixtures/init.sql
  • 데이터베이스 초기 설정
  • 확장 프로그램 설치 (pgvector 등)
  • pnpm create sonamu 실행 시 자동 생성
dumps/
  • pnpm dump 명령으로 생성된 SQL 파일
  • 데이터 백업 저장소
scripts/
  • dump.sh: 현재 DB 데이터를 dumps/에 백업
  • seed.sh: dumps/의 데이터를 DB에 복원
더 알아보기 - 설정 파일

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

​
루트 파일

📁web/
📁src/ - 소스 코드
📄HTMLindex.html - HTML 엔트리포인트
📄JSONpackage.json - 의존성 및 스크립트
📄TSvite.config.ts - Vite 설정
📄JSONtsconfig.json - TypeScript 설정
📄JSONtsconfig.node.json - Node 환경 설정
📄ENV.sonamu.env - 환경 변수

📸 필요: web 디렉토리의 실제 파일 구조 (VS Code Explorer)

vite.config.ts
  • Vite 개발 서버 설정
  • API 프록시 설정 (/api → http://localhost:1028)
  • 경로 별칭 (@ → ./src)
.sonamu.env
  • API 서버 연결 정보
  • API_HOST, API_PORT 설정

​
src/ 디렉토리

📁web/src/
📄TSXmain.tsx - React 진입점
📄TSXApp.tsx - 루트 컴포넌트
📄CSSApp.css - 글로벌 스타일
📄CSSindex.css - 기본 스타일
📁pages/ - 페이지 컴포넌트
📄TSXindex.tsx - 홈 페이지
📁services/ - API 서비스 (자동 생성)
📄TS{Entity}Service.ts
📁admin-common/ - 공통 컴포넌트
📄TSXApiLogViewer.tsx
📄TSXCommonModal.tsx
📁assets/ - 정적 리소스
📄TSvite-env.d.ts - Vite 타입 정의
pages/
  • 라우팅 기반 페이지 컴포넌트
  • React Router 사용
services/
  • API 서버와 통신하는 서비스 레이어
  • 엔티티마다 자동 생성
  • 타입 안전한 API 클라이언트
admin-common/
  • 재사용 가능한 공통 컴포넌트
  • Sonamu UI 관련 컴포넌트
더 알아보기 - 프론트엔드

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

User 엔티티를 생성하면 다음과 같은 구조가 만들어집니다:
📁api/src/application/
📁user/
📄JSONuser.entity.json - Sonamu UI에서 생성
📄TSuser.model.ts - 직접 작성
📄TSuser.types.ts - 자동 생성 (확장 가능)
📄TSuser.model.test.ts - 직접 작성 (선택)
📄TSsonamu.generated.ts - 자동 업데이트
📁database/migrations/
📄SQL20250106120000_create_user.sql - 자동 생성
📁web/src/services/
📄TSUserService.ts - 자동 생성

📸 필요: User 엔티티 생성 후 api/src/application/user 폴더의 실제 파일 구조

​
각 파일의 역할

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

📸 필요: VS Code에서 user.entity.json, user.model.ts, user.types.ts 파일을 나란히 열어 놓은 화면 (split view)

자동 생성 vs 직접 작성 - .entity.json: Sonamu UI에서 작성 - .model.ts: 직접 작성 - .types.ts: 자동 생성되지만 확장 가능 - sonamu.generated.ts: 자동 생성 - 수정 금지 - {Entity}Service.ts: 자동 생성 - 수정 금지
더 알아보기 - 파일별 가이드

​
개발 시 주요 작업 위치

작업 내용위치방법
엔티티 정의api/src/application/{entity}/{entity}.entity.jsonSonamu UI
비즈니스 로직api/src/application/{entity}/{entity}.model.ts직접 작성
커스텀 타입api/src/application/{entity}/{entity}.types.ts직접 확장
API 엔드포인트Model 파일에 @api 데코레이터직접 작성
데이터베이스 설정api/src/sonamu.config.ts직접 작성
서버 설정api/src/sonamu.config.ts직접 작성
테스트 작성api/src/application/{entity}/{entity}.model.test.ts직접 작성
페이지 컴포넌트web/src/pages/직접 작성
공통 컴포넌트web/src/admin-common/직접 작성
자동 생성 파일 주의사항 - sonamu.generated.ts: 절대 수정하지 마세요 - {Entity}Service.ts: 절대 수정하지 마세요 - {entity}.types.ts: 확장은 가능하지만 자동 생성 부분은 수정하지 마세요

​
다음 단계

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

첫 엔티티 만들기

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

개발 워크플로우

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