백엔드 아키텍처 및 폴더 구조

최종 업데이트: 2025년 6월 29일

이 문서는 SurfAI 서비스의 뒤에서 일하는 프로그램이 어떤 기술로 만들어졌고, 어떤 규칙을 따르며, 주요 폴더들이 어떻게 구성되어 있고, 어떻게 실행하는지 쉽게 설명해 드립니다.

1. 사용된 기술들

기본 틀: NestJS (Node.js 기반의 프로그램 기본 틀)
데이터 저장소: PostgreSQL (정보를 저장하는 곳)
데이터 관리 도구: TypeORM (프로그램에서 데이터를 쉽게 다룰 수 있게 돕는 도구)
로그인 관리:
- 방법: Passport.js (로그인 방식을 관리하는 도구)
- 로그인 정보: JWT (로그인 정보를 안전하게 주고받는 방식)
- 구글 로그인: Google OAuth 2.0 (구글 계정으로 로그인할 수 있게 돕는 도구)
- 일반 로그인: passport-local (이메일과 비밀번호로 로그인하는 방식)
실시간 소통: WebSocket (실시간으로 정보를 주고받는 기술)
보안 기능:
- 비밀번호 암호화: bcrypt (비밀번호를 안전하게 저장하는 방법)
- 해킹 방지: csurf (웹사이트 해킹 공격을 막는 기능)
- 쿠키 분석: cookie-parser (사용자 컴퓨터에 저장된 작은 정보(cookie)를 읽는 기능)
정보 확인: class-validator, class-transformer (입력된 정보가 올바른지 확인하는 기능)
API 설명서: Swagger (뒤에서 일하는 프로그램의 기능들을 설명하는 문서 자동 생성 도구)

2. 프로그램 만드는 규칙

뒤에서 일하는 프로그램은 각각의 기능들을 모듈로 나누고, 역할에 따라 계층을 나누는 방식으로 만들어졌어요.

기능별 나누기: 로그인 관련 기능은 AuthModule, 그림 만드는 방법 관련 기능은 WorkflowModule처럼, 각 기능별로 독립적인 부분으로 나누어 만들었어요. 각 부분은 화면 담당, 핵심 기능 담당, 데이터 담당으로 나뉘어 있어요.
역할별 나누기:
- 화면 담당 (Controller): 인터넷 요청을 받아서, 정보가 올바른지 확인한 다음, 핵심 기능을 담당하는 부분에 일을 시키는 역할만 해요. 실제 중요한 계산은 하지 않아요.
- 핵심 기능 담당 (Service): 프로그램의 가장 중요한 계산과 처리를 담당해요. 데이터 저장소와 정보를 주고받거나 다른 서비스들을 호출하는 등 실제 작업이 여기서 이루어져요.
- 데이터 담당 (Repository/Entity): 데이터 저장소와 정보를 주고받는 부분을 쉽게 다룰 수 있도록 도와줘요. TypeORM이라는 도구가 이 역할을 해요.
연결 방식 (DI): 프로그램의 각 부분들이 서로 직접 연결되지 않고, 필요한 것만 받아서 사용하도록 만들었어요. 이렇게 하면 각 부분이 독립적으로 작동해서 나중에 고치거나 테스트하기 쉬워져요.

3. 주요 폴더 구조

/src
├── 📁 admin/              # 관리자만 사용하는 기능들
│   └── 📁 workflow/
├── 📁 auth/               # 로그인, 권한 확인 관련 기능들
│   ├── 📁 guards/
│   └── 📁 strategies/
├── 📁 comfyui/            # AI 그림/영상 만드는 컴퓨터와 소통하는 기능
├── 📁 common/             # 여러 기능에서 공통으로 사용하는 것들
│   ├── 📁 decorators/
│   ├── 📁 dto/            # 정보를 주고받을 때 사용하는 양식
│   ├── 📁 entities/       # 데이터 저장소의 표와 연결되는 정보들
│   ├── 📁 enums/
│   ├── 📁 events/         # 실시간 소통(`WebSocket`)을 위한 기능
│   └── 📁 interfaces/     # 프로그램에서 사용하는 정보들의 형태 정의
├── 📁 generated-output/   # 만들어진 그림/영상 기록 관리 기능
├── 📁 storage/            # 그림/영상 파일 저장소와 연결하는 기능
├── 📁 workflow/           # 그림/영상 만드는 방법(템플릿) 관리 기능
│
└── 📄 main.ts             # 프로그램이 시작될 때 가장 먼저 실행되는 파일

4. 프로그램 실행 및 테스트 방법

개발 환경에서 실행하기

사용자 컴퓨터에 PostgreSQL이라는 데이터 저장소를 설치하고 실행하세요.
프로그램 폴더 안에 .env.development라는 파일을 만들고, 데이터베이스 정보나 로그인 비밀 키 같은 필요한 설정 값들을 입력하세요.
npm install 명령어를 입력해서 프로그램에 필요한 모든 도구들을 설치하세요.
npm run start:dev 명령어를 입력해서 프로그램을 실행하세요. 프로그램은 http://localhost:3000 주소에서 작동할 거예요.

프로그램 테스트하기

프로그램이 잘 작동하는지 확인하기 위해 만들어진 모든 테스트를 실행합니다.
```
npm test
```

5. 꼭 필요한 설정 값들

프로그램을 실행하려면 .env 파일이나 실제 서비스 환경에 다음 설정 값들이 꼭 필요해요.

NODE_ENV: development (개발 중) 또는 production (실제 서비스 중)
PORT: 프로그램이 작동할 인터넷 포트 번호 (기본값: 3000)
데이터 저장소: DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE 또는 DATABASE_URL (데이터 저장소 연결 정보)
로그인: JWT_SECRET, JWT_REFRESH_SECRET, JWT_REFRESH_EXPIRATION_TIME (로그인 정보 관련 비밀 키)
구글 로그인: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (구글 로그인 관련 비밀 키)
서비스 주소: API_BASE_URL (뒤에서 일하는 프로그램의 주소), FRONTEND_URL (웹사이트 화면의 주소), ROOT_DOMAIN (서비스의 기본 인터넷 주소)
그림/영상 만드는 컴퓨터: COMFYUI_HOST, NGINX_USERNAME, NGINX_PASSWORD (그림/영상 만드는 컴퓨터 연결 정보)
파일 저장소: R2_ACCOUNT_ID, R2_BUCKET_NAME, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY (그림/영상 파일 저장소 연결 정보)
관리자: ADMIN_EMAILS (관리자 이메일 주소)

1. 사용된 기술들​

2. 프로그램 만드는 규칙​

3. 주요 폴더 구조​

4. 프로그램 실행 및 테스트 방법​

개발 환경에서 실행하기​

프로그램 테스트하기​

5. 꼭 필요한 설정 값들​