개요
앞선 글에서는 사내 문서 검색 시스템 도입의 필요성과 RAG 기술 개요, 그리고 프로젝트 환경을 간략히 소개하였다. 이번 글에서는 본격적인 개발에 앞서, 프로젝트 전체 저장소를 어떻게 설계하고 초기화했는지를 다뤄보겟다.
구조화가 왜 중요할까?
다양한 도구와 언어, 협업 참여자가 섞인 프로젝트일수록 디렉터리 구조와 개발 규칙의 명확한 정립이 중요하다. 특히 프론트엔드, 백엔드, 인프라가 각기 다른 기술 스택으로 구성된 경우, 프로젝트 구조 자체를 정립하지 않으면 유지보수에 어려움을 겪게된다.
프로젝트 초기화 작업 흐름
이번 작업의 주요 목표는 다음과 같다.
- 전체 프로젝트 저장소 생성 및 GitHub 연동
- 프론트엔드, 백엔드, 인프라 디렉터리 분리 및 템플릿 배치
- GitHub Actions를 활용한 CI/CD 파이프라인 구성
- 코드 컨벤션과 작업 방식 문서화
- Vooster와 Cursor 기반 개발 흐름 정착
디렉터리 구조 (TRD 기반 도메인 모듈화)
├── frontend/ # 사용자 인터페이스 (Next.js 14)
├── backend/ # FastAPI 기반 API 서버
├── infra/ # Terraform + Helm 기반 인프라 코드
├── docs/ # 개발 가이드 및 문서
├── .github/ # GitHub Actions 워크플로
├── .cursor/ # Cursor AI 규칙 파일
├── .vooster/ # 태스크 관리 및 문서 메타
기술 스택
| 프론트엔드 | React 18, Next.js 14, TypeScript, Tailwind CSS |
| 백엔드 | Python 3.11, FastAPI, SQLAlchemy, Pydantic |
| 인프라 | Docker, Kubernetes, Helm, Terraform, GitHub Actions |
| 모니터링 | Prometheus, Grafana, Sentry |
| 데이터베이스 | PostgreSQL, Milvus, Redis |
자동화 & 품질 관리
- CI/CD: GitHub Actions로 프론트/백엔드 자동 빌드 및 테스트 설정
- 테스트 프레임워크: Jest (프론트엔드), pytest (백엔드)
- 코드 품질 도구: ESLint, Prettier, Black, pre-commit hook
- Branch 전략: Git Flow 기반 브랜치 네이밍 전략 적용
- 문서화: docs/DEVELOPMENT_GUIDE.md 에 모든 개발 규칙 기록
관련 용어 정리
| Cursor | 코드 기반 AI 개발 도구. GPT, Claude 등과 연동되어 개발자의 워크플로우를 보조함 |
| Vooster | 프로젝트 기획, 구조 설계, 문서 관리를 통합적으로 도와주는 태스크 기반 협업 도구 |
| FastAPI | 파이썬 기반의 빠르고 가벼운 웹 프레임워크로, API 서버 개발에 자주 사용됨 |
| Next.js | React 기반의 프레임워크로, 서버 사이드 렌더링과 정적 페이지 생성을 지원함 |
| Tailwind CSS | 유틸리티 기반 CSS 프레임워크로, 빠른 UI 스타일링을 지원함 |
| Milvus | 대용량 벡터 데이터를 저장하고 검색하는 데 특화된 오픈소스 벡터 DB |
| Helm | Kubernetes에서 애플리케이션을 패키징하고 배포할 수 있게 도와주는 도구 |
| Terraform | 클라우드 인프라를 코드로 선언하고 자동으로 배포/관리할 수 있게 해주는 IaC 도구 |
| Docker | 앱을 컨테이너라는 독립된 환경으로 패키징하여 어디서나 동일하게 실행 가능하게 만드는 기술 |
| Kubernetes | (K8s) 여러 개의 컨테이너를 자동으로 배포, 확장, 운영하는 오케스트레이션 플랫폼 |
| CI/CD | 코드 변경을 자동으로 테스트하고 배포하는 개발 방식 (지속적 통합/지속적 배포) |
| IaC | (Infrastructure as Code) 서버, 네트워크 같은 인프라를 코드로 정의하고 버전 관리하는 방식 |
개발 문화 도입: Github + Cursor + Vooster + Notion
Vooster를 통해 프로젝트를 관리하고 Cursor 를 통해 개발을 진행한 후 검증이 완료된 개발건을 Github 에 커밋하고 마지막으로 작업한 내역을 Notion을 통해 정리. (VoosterMCP, NotionMCP, GithubCLI 사용)
https://www.notion.so/Project_Repository_Setup-T-001-22d72b9b162381e3926adcaa41684666
Project_Repository_Setup [T-001] | Notion
📋 개요 (OVERVIEW)
www.notion.so
정리된 노션 링크
마무리
이번 글에서는 프로젝트 저장소를 어떻게 구성했는지, 그리고 어떤 기준으로 초기 세팅을 마쳤는지 정의하였으며
다음 글에서는 AWS EKS 기반 Kubernetes 클러스터 및 인프라 스택을 Terraform과 Helm을 통해 어떻게 자동화했는지를 다룰 예정이다.
'사이드 프로젝트' 카테고리의 다른 글
| RAG 기반 문서 검색 시스템 - 5(문서 업로드 및 S3 저장/바이러스 검사 구현) (2) | 2025.07.21 |
|---|---|
| RAG 기반 문서 검색 시스템 - 4(인증/권한/사용자/ORM 연동) (0) | 2025.07.21 |
| RAG 기반 문서 검색 시스템 - 3(Next.js 초기화 및 인증 연동) (2) | 2025.07.18 |
| RAG 기반 문서 검색 시스템 - 2 (AWS EKS 인프라 구축기) (2) | 2025.07.17 |
| RAG 기반 문서 검색 시스템(개요 및 프로젝트 설계) (0) | 2025.07.15 |