[설계] 프로젝트 부터 데이터 파이프 라인

정운·2026년 3월 26일

ItsMe

목록 보기

2/10

시작하며

이 프로젝트를 시작하며 단순하게 결과물을 띡 보여주는게 아니라 설계와 개발 과정 전체를 보여주는 것을 목표로 시작했다.
기존 포트폴리오는 "무엇을 만들었는가"에 집중 했다면, 나는 "어떻게 생각하고 만들었는가"를 보여주는 것 이다.

전체 아키텍쳐 설계

프로젝트는 다음과 같은 구조를 기반으로 설계했다.

app/     -> UI레이어
lib/     -> 데이터 처리 및 비즈니스 로직
content/ -> Markdown 기반 데이터

각 역할을 명확하게 분리하는 것이 목표 였다.

app: UI 렌더링
lib: 데이터 가공 및 변환
content: 데이터 소스

이 구조를 통해 유지보수성과 확장성을 확보하고자 했다.

데이터 관리 방식(Markdown VS Json)

Json 으로 데이터를 관리하는것과 Markdown 또는 MDX방식으로의 데이터 관리를 고민했다.
일단 백엔드서버 없이 운영하는 것을 생각했기에 따로 DB는 생각하지 않았고, 로컬 파일로 관리하는것이 시작이었다.

그중 굳이 Markdown을 선택한 이유는

단순한 데이터가 아니라 데이터로 설명 가능한 콘텐츠를 담고 있었고
프로젝트 설명, 문제 해결 과정 등을 Markdown파일 안에 담아 낼수 있기 때문

title: "포트폴리오 프로젝트"
summary: "Next.js 기반 포트폴리오"
tags: ["Next.js, "TDD"]
status: "published"
createAt: "2026-03-26"

## 프로젝트 설명

이렇게 단순한 데이터 포맷이 아니라 콘텐츠를 포함한 데이터 구조라서 선택했다.

파일 네이밍 & slug 전략

slug는 별도로 관리하지 않고, 파일명을 기반으로 생성하도록 설계했다.

my-first-project.md -> my-first-project

이렇게 한 이유는:

데이터와 URL 일관성 유지
관리 포인트 최소화
단일 출처 확보

데이터 파이프라인 설계

Markdown 파일
-> 파일 읽기
-> frontmatter 파싱
-> projectMapper
-> Project 객체
-> UI

이렇게 단계를 정했다.

Markdown 파일을 projectMatter로 읽고 데이터 영역과 설명 영역을 parsing
파싱한 데이터를 ProjectMapper 를 통해 Project 객체로 만들고
UI에 뿌려주기

타입 설계

데이터 타입은 두가지로 나누어서 설계 했다.

interface RawFrontmatter = {
//* 백그라운드에서 동작 하는 필드
  thumbnail?: string;
  size?: number[];
  status?: "draft" | "published";
  //* 상단에 있는 필드
  title?: string;
  tags?: string[];
  createdAt?: string;
  publishedAt?: string;
  githubLink?: string;
  velogLink?: string;
  summary?: string;
}

interface Project = {
  slug: string;
  thumbnail: string;
  size: number[];
  status: "draft" | "published";
  title: string;
  tags: string[];
  createdAt: string;
  publishedAt: string;
  githubLink: string;
  velogLink: string;
  summary: string;
  contents: string;
}

불완전한 RawFrontmatter 와 정제된 Project 이렇게 두가지 타입을 나눴다.
이렇게 나눈게 적절한가에 대한 고민은 답을 내지는 못했지만, 추후에 변경될 가능성이 있다.

구현 내용

현재까지의 구현은

Markdown 파일 구조 설계
파일 읽기 로직 구현
frontmatter 파싱
slug 생성
projectMapper 구현
getAllProjects 구현

즉 데이터 -> UI 직전 단계 까진 구현이 되어 있다.

TDD에 대한 고민

원래는 전체를 TDD방식으로 구현 하면서 하나하나 Test 먼저 하려고 했지만, TDD로 진행하는 것이 처음 이기도 하고
사용법자체에 익숙하지 않아서 구현 먼저 진행하게 되었다.
중요 로직들은 TDD로 해놓은 것도 있지만, 방식 자체의 효용성에 대해 생각해 보게 된다.
아직 TDD 자체에 대한 이해도가 너무 낮은것 같다...