[18주차] - [9기] 타입스크립트로 함께하는 웹 풀 사이클 개발(React, Node.js) 10회차 - 79

아키텍처와 개발 방법론, 왜 함께 고민해야 할까?

프로젝트를 처음 시작하면 많은 개발자들이 가장 먼저 기능 구현에 집중합니다.
“일단 돌아가게 만들자”라는 생각은 자연스럽고 실제로 초기 개발 단계에서는 매우 중요합니다. 하지만 프로젝트 규모가 커지고 협업 인원이 늘어나기 시작하면 단순히 기능만 동작하는 코드로는 한계가 생깁니다.

• 어디에 어떤 코드가 있는지 찾기 어렵고
• 새로운 기능을 추가할 때 기존 기능이 깨지며
• 협업 과정에서 충돌이 자주 발생하고
• 배포 이후 장애 대응 속도도 느려집니다.

이 문제를 해결하기 위해 등장하는 개념이 바로 아키텍처(Architecture) 와 개발 프로세스(Process) 입니다.

아키텍처는 “프로젝트를 어떤 구조로 설계할 것인가”에 대한 이야기이고,
개발 프로세스는 “어떤 방식으로 협업하고 개발할 것인가”에 대한 이야기입니다.

이 두 가지는 따로 존재하는 것이 아니라 서로 긴밀하게 연결되어 있습니다.
좋은 아키텍처 위에서 효율적인 개발 프로세스가 동작할 때 프로젝트는 빠르고 안정적으로 성장할 수 있습니다.

이번 글에서는 실제 웹 프로젝트를 개발한다는 관점에서 아키텍처와 개발 프로세스를 함께 정리해보겠습니다.

---

1. 아키텍처(Architecture)란 무엇인가?

소프트웨어 아키텍처는 쉽게 말하면 프로젝트의 “설계도”입니다.

건물을 지을 때도 설계도가 없으면 구조가 무너지듯,
소프트웨어 역시 구조 없이 개발하면 유지보수가 매우 어려워집니다.

아키텍처는 다음과 같은 것들을 결정합니다.

• 폴더 구조
• 데이터 흐름
• 컴포넌트 분리 방식
• 서버와 클라이언트 통신 방식
• 상태 관리 방식
• 데이터베이스 구조
• 배포 구조
• 캐시 전략
• 인증 방식

즉, 프로젝트 전체의 방향성을 정하는 작업입니다.

---

2. 왜 아키텍처가 중요한가?

2-1. 유지보수가 쉬워진다

프로젝트 초기에는 코드가 적기 때문에 큰 문제가 없어 보입니다.
하지만 기능이 늘어나면 상황이 완전히 달라집니다.

예를 들어:

- 로그인 기능 추가
- 실시간 채팅 추가
- 랭킹 시스템 추가
- 알림 기능 추가
- 통계 기능 추가

 

기능이 계속 늘어나는데 구조가 정리되어 있지 않다면 코드 의존성이 꼬이기 시작합니다.

반면 좋은 아키텍처를 적용하면:

• 기능별로 파일이 분리되고
• 역할이 명확해지며
• 수정 범위를 예측할 수 있고
• 테스트 작성도 쉬워집니다.

---

2-2. 협업 효율이 올라간다

팀 프로젝트에서는 특히 중요합니다.

아키텍처가 정리되어 있으면:

• 프론트엔드 개발자는 UI 영역에 집중할 수 있고
• 백엔드 개발자는 API와 데이터 로직에 집중할 수 있으며
• 공통 타입이나 인터페이스를 공유할 수 있습니다.

특히 모노레포(monorepo) 구조에서는 이런 장점이 더욱 커집니다.

예를 들어:

apps/
 ├─ frontend
 ├─ backend
packages/
 ├─ shared-types
 ├─ ui

 

이렇게 구성하면 프론트와 백엔드가 동일한 타입을 사용할 수 있어 API 스펙 불일치를 줄일 수 있습니다.

---

3. 대표적인 아키텍처 구성 요소

3-1. 프론트엔드 아키텍처

프론트엔드에서는 주로 다음을 고민합니다.

컴포넌트 구조

components/
 ├─ common
 ├─ game
 ├─ layout

 

• 공통 UI
• 게임 전용 UI
• 레이아웃

등 역할별로 분리합니다.

---

상태 관리

프로젝트가 커질수록 상태 관리가 중요해집니다.

대표적으로:

• React Context
• Zustand
• Redux
• React Query

등을 사용합니다.

예를 들어 실시간 게임에서는:

• 플레이어 상태
• 게임 진행률
• 소켓 연결 상태

등이 계속 변하기 때문에 상태 관리 구조가 매우 중요합니다.

---

API 통신 구조

services/
 ├─ auth.ts
 ├─ game.ts
 ├─ ranking.ts

 

API 요청을 분리하면 유지보수가 쉬워집니다.

---

4. 백엔드 아키텍처

백엔드는 데이터와 비즈니스 로직을 관리합니다.

대표적인 구조는 다음과 같습니다.

src/
 ├─ modules
 ├─ common
 ├─ database
 ├─ auth

 

NestJS 같은 프레임워크에서는 모듈 단위 구조를 많이 사용합니다.

---

4-1. 계층 분리

Controller

요청을 받는 역할

Service

비즈니스 로직 처리

Repository / ORM

DB 접근

이렇게 분리하면 책임이 명확해집니다.

---

4-2. 인증 구조

대표적으로:

• JWT
• Refresh Token
• Cookie 기반 인증

등이 사용됩니다.

특히 실시간 게임에서는 소켓 인증도 함께 고려해야 합니다.

---

4-3. 캐시 전략

트래픽이 많아지면 DB만으로는 한계가 옵니다.

그래서 Redis 같은 캐시 서버를 사용합니다.

예:

- 랭킹 캐시
- 유저 정보 캐시
- 게임 결과 캐시

 

캐시는 성능 향상에 매우 큰 영향을 줍니다.

---

5. 실시간 서비스에서의 아키텍처

최근 프로젝트에서는 실시간 기능이 매우 중요합니다.

예를 들어:

• 채팅
• 실시간 게임
• 협업 툴
• 스트리밍 서비스

등은 WebSocket 기반 구조를 사용합니다.

---

5-1. Socket 구조

실시간 게임에서는 일반 HTTP보다 소켓 이벤트 설계가 중요합니다.

예:

client -> typing:update
server -> player:progress
server -> game:end

 

이벤트 단위를 명확하게 설계해야 합니다.

---

5-2. 실시간 데이터 처리

타이핑 게임을 예로 들면:

• 입력 검증
• 정확도 계산
• 타수 계산
• 진행률 계산

이 모두 실시간으로 처리되어야 합니다.

이 과정에서:

• throttle
• debounce
• event batching

같은 최적화 기법도 중요해집니다.

---

6. 개발 프로세스(Process)

좋은 구조만 있다고 프로젝트가 성공하는 것은 아닙니다.

협업 방식도 중요합니다.

---

7. 일반적인 개발 프로세스

대부분의 팀 프로젝트는 다음 흐름으로 진행됩니다.

기획
→ 와이어프레임
→ 디자인
→ 아키텍처 설계
→ API 설계
→ 개발
→ 테스트
→ 배포
→ 유지보수

 

---

8. 와이어프레임 단계

와이어프레임은 화면 설계 단계입니다.

보통 Figma를 사용합니다.

이 단계에서는:

• 화면 흐름
• 사용자 동선
• 필요한 기능

등을 정리합니다.

프론트엔드 개발자는 이 시점부터:

• 컴포넌트 분리
• 상태 구조
• 페이지 구조

를 고민하기 시작합니다.

---

9. API 설계

프론트와 백엔드는 API 명세를 기준으로 협업합니다.

보통 Swagger(OpenAPI)를 사용합니다.

예:

 

GET /games/current
POST /games/start
POST /games/end

 

API 설계가 명확해야:

• 프론트 작업 병렬 진행 가능
• Mock 데이터 사용 가능
• 협업 충돌 감소

효과를 얻을 수 있습니다.

---

10. 브랜치 전략

협업에서는 Git 전략도 매우 중요합니다.

대표적으로:

main
develop
feature/*
hotfix/*

 

구조를 사용합니다.

---

10-1. PR(Pull Request)

기능 개발 후 바로 merge하지 않습니다.

PR을 통해:

• 코드 리뷰
• 테스트 확인
• 구조 검토

를 진행합니다.

좋은 코드 리뷰 문화는 프로젝트 품질을 크게 높여줍니다.

---

11. 코드 컨벤션

컨벤션이 없으면 코드 스타일이 모두 달라집니다.

그래서:

• ESLint
• Prettier
• Biome

등을 사용합니다.

예:

- 변수명 규칙
- 함수명 규칙
- import 정렬
- 세미콜론 여부

 

를 통일합니다.

---

12. 테스트 프로세스

테스트는 프로젝트 안정성을 높입니다.

대표적으로:

단위 테스트(Unit Test)

함수 단위 테스트

통합 테스트(Integration Test)

API 흐름 테스트

E2E 테스트

실제 사용자 흐름 테스트

특히 백엔드에서는:

- 200 성공
- 400 예외
- 401 인증 실패
- 500 서버 에러

 

케이스를 반드시 테스트해야 합니다.

---

13. 배포 프로세스

개발이 끝나면 배포가 필요합니다.

최근에는:

• Docker
• Render
• Vercel
• AWS
• GitHub Actions

등을 많이 사용합니다.

CI/CD를 구축하면:

git push
→ 테스트 실행
→ 빌드
→ 자동 배포

 

흐름을 자동화할 수 있습니다.

---

14. 좋은 개발 문화란?

좋은 프로젝트는 단순히 코드만 좋은 것이 아닙니다.

다음 요소들이 함께 중요합니다.

• 명확한 커뮤니케이션
• 적극적인 코드 리뷰
• 문서화
• 테스트 문화
• 협업 태도
• 책임 분리

특히 문서화는 생각보다 훨씬 중요합니다.

Swagger 문서나 README만 잘 정리되어 있어도 신규 팀원이 빠르게 적응할 수 있습니다.

---

15. 결국 중요한 것은 “확장 가능성”

초기에는 단순하게 시작해도 됩니다.

하지만 프로젝트는 계속 성장합니다.

그 과정에서:

• 유지보수 가능한 구조
• 협업 가능한 구조
• 테스트 가능한 구조
• 확장 가능한 구조

를 만들어두는 것이 매우 중요합니다.

좋은 아키텍처와 개발 프로세스는 당장의 속도를 조금 늦출 수 있습니다.
하지만 장기적으로 보면 훨씬 빠르고 안정적인 개발을 가능하게 만듭니다.

---

마무리

개발은 단순히 코드를 작성하는 작업이 아닙니다.

• 어떤 구조로 만들 것인가?
• 어떻게 협업할 것인가?
• 어떻게 유지보수할 것인가?
• 어떻게 확장할 것인가?

를 함께 고민하는 과정입니다.

아키텍처와 개발 프로세스는 처음에는 어렵고 복잡하게 느껴질 수 있습니다.
하지만 프로젝트 경험이 쌓일수록 왜 중요한지 체감하게 됩니다.

특히 팀 프로젝트나 실무 환경에서는:

• 구조 설계 능력
• 협업 능력
• 문서화 능력
• 테스트 설계 능력

이 개발자의 중요한 역량이 됩니다.

결국 좋은 개발자는 단순히 기능을 구현하는 사람이 아니라,
“오래 유지될 수 있는 시스템”을 만드는 사람이라고 생각합니다.