시스템 구성

요청의 흐름

1. 사용자가 Next.js 화면에서 조회·검색을 요청합니다.
2. 화면은 같은 사이트의 /api/... 경로로 BFF(화면 전용 서버 중계 계층)를 호출합니다.
3. BFF는 환경 설정의 Backend 주소와 API prefix를 조합해 Gateway로 요청합니다.
4. FastAPI가 업무 로직을 수행하고 PostgreSQL을 조회합니다.
5. 외부 소비 서비스의 Backend는 BFF를 거치지 않고 공개 Backend API를 호출합니다.

그림은 연결 관계를 요약합니다. 실제 VM·DB 개수와 모든 네트워크 보안 설정을 표현하지 않습니다. STG와 PROD의 주소·DB는 환경별로 분리합니다.

저장소의 책임

위치	책임
frontend/src/app/	화면 경로, 화면 전용 컴포넌트·상태, API BFF
frontend/src/features/	분야별 API 계약·모델
frontend/src/components/	공통 화면 요소·내비게이션·Provider
frontend/src/lib/	서버 연결·기술 유틸·공통 계산
backend/app/router/	HTTP 요청·응답 계약
backend/app/modules/	분야별 업무 규칙·유스케이스·저장소 구현
backend/app/core/	설정·DB·트랜잭션·앱 조립
backend/alembic/	DB 스키마 변경
backend/scripts/	검토·게시·조회 등 운영 명령
docs/ · ops/ · .github/	설계·가이드, 운영 자료, CI/CD

Backend에는 현재 사용 중인 기존 조회·사전 처리 계층도 함께 있습니다. 이름에 legacy나 compatibility가 있다는 이유만으로 미사용 코드라고 판단하지 않습니다.

Frontend 연결과 조회 상태

Backend 주소는 서버 설정 PROCEDURE_API_BASE에서 읽습니다. 브라우저 코드에는 로컬 IP나 배포 환경 주소를 직접 넣지 않습니다.

공통 React Query 캐시는 조회 결과를 5분 동안 재사용하며, 오래된 결과는 재방문 시 기존 내용을 보여주면서 갱신합니다. 사용하지 않는 캐시는 30분 후 정리합니다. 메뉴에 포인터·포커스가 들어오면 필요한 데이터를 미리 조회합니다. 이는 브라우저 메모리의 조회 기능이며 DB 저장이나 게시 승인을 대신하지 않습니다.

Backend 업무 경계

일반 조회는 기존 데이터의 응답 계약을 유지합니다. 통합 검색은 게시된 Canonical 릴리스에 속한 데이터와 검색 색인을 사용합니다. 게시 릴리스가 없을 때 미승인 초안을 대신 반환하지 않습니다.

순수 업무 규칙은 HTTP·ORM·DB 세션과 분리하고 애플리케이션 계층이 저장소와 트랜잭션을 조율합니다. 도메인 객체가 존재하는 것과 모든 관리 API·화면이 완성된 것은 구분합니다.

가독성 기준

• 화면 표시, 서버 연결, 업무 판단은 각 책임이 드러나는 위치에 둡니다.
• 공통화는 실제 공유하는 요소에 적용하고 화면별 데이터 로딩 반복을 줄입니다.
• 파일을 균일한 크기로 쪼개는 것보다 변경할 위치와 흐름이 쉽게 읽히는지를 봅니다.
• API 변경은 기존 소비자의 응답·번역 처리에 미치는 영향을 함께 확인합니다.

구체적인 구현 계약은 도메인 책임과 Frontend 구조 결정에서 확인합니다.