본문으로 건너뛰기

개요

코드베이스 원칙은 하나의 애플리케이션이 하나의 버전 관리 기준을 가져야 한다는 뜻입니다. 배포 대상이 개발 서버, 검증 서버, 운영 서버처럼 여러 개일 수는 있지만, 어떤 소스가 어떤 산출물로 배포되었는지는 항상 추적 가능해야 합니다.

HandStack은 단일 웹앱이라기보다 호스트, 모듈, 공통 인프라, 운영 도구가 함께 구성된 플랫폼입니다. 따라서 코드베이스를 이해할 때는 개별 화면 파일보다 먼저 저장소의 책임 경계를 이해해야 합니다.

HandStack 저장소의 기준​

HandStack 메인 저장소는 다음 영역으로 나뉩니다.

  • 1.WebHost: ack, agent, deploy, forbes 같은 실행 호스트
  • 2.Modules: wwwroot, transact, dbclient, function, repository, logger, checkup, command, graphclient, prompter, forwarder 등 기능 모듈
  • 3.Infrastructure: 공통 라이브러리와 웹/데이터 기반 기능
  • 4.Tool: handstack, bundling, ports, publish-package, updater 같은 CLI 도구
  • 루트 스크립트: env, install, build, publish, assemblies 작업을 위한 .bat, .ps1, .sh

업무 모듈은 이 구조 위에 별도의 모듈 디렉터리로 추가됩니다. 업무 모듈도 module.json, Contracts, wwwroot, 빌드/관리 스크립트처럼 HandStack이 기대하는 형식을 지켜야 합니다.

신규 개발자가 알아야 할 점​

코드베이스를 다룰 때 가장 중요한 기준은 "실행되는 파일이 어디에서 왔는지 설명할 수 있어야 한다"는 것입니다.

  • 기능 수정은 저장소에 남겨야 하며, 서버에서 직접 고친 파일을 기준으로 삼지 않습니다.
  • HandStack 코어와 업무 모듈의 책임을 섞지 않습니다.
  • 공통 기능은 3.Infrastructure 또는 기본 모듈의 역할을 먼저 확인한 뒤 확장합니다.
  • 배포 산출물은 publish 흐름으로 만들어진 결과를 기준으로 합니다.
  • 임시 패치가 필요하더라도 이후 코드베이스에 반영할 경로를 기록합니다.

마치며​

HandStack에서 코드베이스는 단순한 Git 저장소가 아니라 개발, 빌드, 배포, 운영 자동화의 출발점입니다. 신규 개발자는 화면이나 SQL부터 보기 전에 ack가 모듈을 로드하고, 모듈이 계약과 정적 자산을 제공하는 구조를 먼저 이해해야 합니다.