C4 Model for Visualizing Frontend Architecture (Feat. FSD)

C4 Model for Visualizing Frontend Architecture

1. C4 Model for Visualizing Frontend Architecture

먼저, C4 모델은 소프트웨어 아키텍처를 네 가지 수준으로 시각화합니다. (Context, Container, Component, Code)

이 접근법은 시스템을 직관적이고 명확하게 이해할 수 있도록 돕습니다.

그러나 전통적인 C4 모델은 백엔드 중심의 시스템에 적합하며, 프런트엔드의 특수성을 담기엔 한계가 있습니다.

Visualizing Frontend Architecture는 이러한 한계를 극복하기 위해 설계되었습니다.

이 방법론은 프런트엔드의 도메인 특화된 요구사항과 기술 스택을 시각적으로 표현할 수 있게 합니다.

크게 아래와 같이 구성될 수 있습니다.

 

FE 앱을 Context(전체 시스템에서의 FE의 역할) → Container(앱 내부의 큰 범위 컴포넌트 그룹) → Component(각 컨테이너 안의 컴포넌트들) → Code(실제 파일/코드 레벨)

 

이렇게 점진적으로 표현하면서, 팀 내부에서 우리가 어떤 구조로 이 앱을 만들고 있는지를 구체적으로 시각화합니다.

 

이 접근이 매력적인 이유는, 코드 레벨에 들어가기 전 우리가 왜 이 구조를 택하고, 각 부분이 어떤 역할을 맡고 있는지를 한 장의 다이어그램(혹은 여러 단계의 다이어그램)으로 팀원 모두가 공유할 수 있다는 점이었습니다.

2. FSD(Feature-Sliced Design)

FSD는 최근 들어 많은 프런트엔드 개발자들이 관심을 갖는 폴더 구조화 방식이자 아키텍처 패턴입니다.

기능(Feature) 단위로 파일과 폴더를 구조화하고, 도메인별로 코드가 모듈화 되어야 한다는 점을 강조합니다.

자세한 내용은 아래의 블로그 글을 참고하시기 바라며 간단하게 FSD에 대해 소개하겠습니다.

1) 장점

• 도메인(혹은 기능) 단위로 분리되어 재사용성이 올라감.
• 새로 들어온 팀원이 한 기능(Feature)을 이해하기 쉽도록 코드가 모듈화 됨.
• 규모가 커질수록 전체 프로젝트를 쉽게 파악 가능.

2) 단점

• ‘Feature’라는 개념 정의가 팀별로 달라질 수 있음.
• 유지보수와 가이드라인 적용이 제대로 되지 않으면, 오히려 폴더와 파일만 많아질 수 있음.
• 설계를 잘못하면 컴포넌트 간 의존성 관리가 복잡해짐.

2024.07.27 - [Tip] - FSD 폴더 구조 소개 (feat. NextJS App Router, Pages)

FSD 폴더 구조 소개 (feat. NextJS App Router, Pages)

3. 왜 Visualizing Frontend Architecture인가?

1) 팀 내 공통 이해도 상승

C4 모델 자체가 아키텍처를 ‘큰 그림’부터 시작해 단계별로 세분화하는 방식을 취합니다.
PM, 디자이너, 백엔드 개발자 등 다양한 직군이 협업을 해야 하는데, FSD는 주로 프런트엔드 개발자에게만 익숙한 개념인 반면, C4는 아키텍처 다이어그램을 전사적으로 쉽게 공유할 수 있다는 장점이 있습니다.

2) 빠른 의사소통과 협업

시각화된 다이어그램을 통해 어떤 컨테이너가 어디서 어떤 데이터를 받아 오는지, 컴포넌트 간 의존성이 어떻게 형성되어 있는지를 명확히 표현합니다.
그 결과 "이 기능은 저쪽 모듈과 어떻게 연결되지?" 같은 질문이 나오면 C4 다이어그램 레벨에서 먼저 확인하고, 실제 코드 레벨로 들어가 볼 수 있었습니다.
이는 팀원들이 불필요한 커뮤니케이션 시간을 줄이면서, 정확한 의사소통을 하는 데 큰 장점이 됩니다.

3) 도메인 지식의 체계화

Visualizing Frontend Architecture는 FE 레이어에서 일어나는 모든 도메인 로직을 시각적으로 묶어 볼 수 있게 합니다.

• 유저 인증 로직(로그인/회원가입/비밀번호 재설정 등)은 하나의 ‘도메인 컨테이너’로 묶기
• 결제 로직(장바구니/결제 API 호출/영수증 발행 등)은 또 다른 ‘도메인 컨테이너’로 묶기

이런 식으로 컨테이너 레벨에서 그룹화해 두면, 세부 컴포넌트들이 어느 도메인에 속해 있고, 어디에서 재사용 가능할지 효과적으로 파악할 수 있습니다.

4) 확장성과 유지보수 편의

C4 기반의 시각화는 프로젝트가 커져도 단계별 다이어그램을 업데이트하면 됩니다.

• Context 다이어그램은 서비스가 확장됨에 따라 바뀌는 외부 연동(예: 신규 API)만 추가
• Container 다이어그램은 FE 내 주요 컨테이너(서비스, 도메인, 라이브러리 등)에 변경이 있을 때만 수정
• Component 다이어그램은 특정 컨테이너 안에서 컴포넌트 구조가 달라질 때 업데이트
• Code 레벨은 코드 자체 리팩토링 시에 바뀜

다른 복잡한 아키텍처 방식에 비해, 어느 레벨에서 수정이 발생했는지를 명확히 파악하고, 필요한 부분만 수정할 수 있어 유지보수가 훨씬 편해집니다.

 

물론 어느 한 폴더 구조가 좋고 다른 구조는 별로라는 것은 아닙니다.

소개한 폴더 구조들을 완벽히 따라 해야 되는 것도 아니며, 각각의 상황에 맞게 제외하거나 합쳐서 상황에 맞는 최적의 폴더 구조를 설정하시기를 바라겠습니다.

 

마지막으로, Next.js App Router 환경에서 FSD와 C4를 병행해 사용하는 간단한 디렉터리 예시를 살펴보겠습니다.

아래 구조는 FSD 관점에서 기능(도메인) 별 폴더를 분리하고, 동시에 C4의 Container/Component 레벨 다이어그램으로 해당 기능들을 시각화해 볼 수 있도록 구성한 예시입니다.

app-router-nextjs-project/
├─ app/
│  ├─ (blog)/
│  │  ├─ layout.tsx          // 블로그 도메인 전용 레이아웃
│  │  ├─ page.tsx            // /blog
│  │  ├─ [slug]/
│  │  │  └─ page.tsx         // /blog/:slug
│  │  └─ components/
│  │     └─ PostItem.tsx     // 블로그 글 목록/아이템 컴포넌트
│  │
│  ├─ (auth)/
│  │  ├─ login/
│  │  │  ├─ page.tsx
│  │  │  └─ components/
│  │  │     └─ LoginForm.tsx
│  │  ├─ register/
│  │  │  ├─ page.tsx
│  │  │  └─ components/
│  │  │     └─ RegisterForm.tsx
│  │  └─ layout.tsx          // auth 도메인 전용 레이아웃
│  │
│  ├─ layout.tsx             // 최상위 레이아웃
│  ├─ page.tsx               // 루트('/') 경로
│  └─ global.css
│
├─ components/               // 전역적으로 재사용할 수 있는 공통 컴포넌트
├─ hooks/                    // 전역 훅(예: useAuth, useFetch 등)
├─ lib/                      // API 클라이언트, 유틸, 상수 등
├─ docs/
│  └─ architecture-diagrams/
│     ├─ context-diagram.png
│     ├─ container-diagram.png
│     └─ component-diagram-auth.png
├─ package.json
└─ tsconfig.json

 

여기서 (blog), (auth) 같은 Route Group 폴더는 실제 URL에 노출되지 않으면서도, FSD의 피처(기능) 단위 분리 개념을 살릴 수 있으며, 동시에 C4 모델의 Container 레벨에서 (blog), (auth) 같은 도메인을 독립 컨테이너로 바라봅니다.

그리고 하위 컴포넌트와의 연관관계를 Component 레벨 다이어그램으로 시각화하면 팀원 간 이해도가 크게 높아집니다.

예시를 참고하여 FSD와 C4 Model에서 좋다고 생각하는 부분을 가지고 오고 필요 없는 부분을 제외하며 폴더 구조를 만든다면 개발 속도와 협업 효율을 동시에 끌어올릴 수 있을 것입니다.