아키텍처 개요

GrantForge는 Spring Boot 4 애플리케이션(Java 17 바이트코드)으로, 도메인별로 여러 Maven 모듈로 나뉘어 하나의 실행 가능한 배포 패키지로 빌드됩니다. 콘솔은 Vue 3 단일 페이지 애플리케이션이며 서버가 함께 제공합니다.

모듈

서버와 공유 인프라는 core/에 있고, 서버가 로드하는 서비스 타입 플러그인은 plugins/에, 대상 시스템에 배포되는 구체적인 에이전트는 agents/에 있습니다. core/grantforge-agent-core는 공유 프로토콜과 런타임을 제공하고, agents/grantforge-agent-hdfs-*는 HDFS NameNode용 권한 부여 어댑터를 제공합니다.

flowchart TB
  server[grantforge-server] --> oauth[grantforge-oauth]
  server --> service[grantforge-service]
  server --> authz[grantforge-authz]
  oauth --> authz
  service --> host[grantforge-plugin-host]
  service --> identity
  host --> api[grantforge-plugin-api]
  authz --> identity[grantforge-identity]
  identity --> audit[grantforge-audit]
  audit --> persistence[grantforge-persistence]
  persistence --> common[grantforge-common]
  agent[대상 시스템의 에이전트] -.-> agentcore[grantforge-agent-core]
  agentcore --> engine[grantforge-policy-engine]

위 그림은 모듈 사이의 의존 관계입니다(하위 계층의 common, persistence 등은 모든 모듈이 의존하므로, 그림에서 반복되는 화살표는 생략했습니다). 정책 엔진은 다른 모듈에 의존하지 않으며 대상 시스템의 에이전트가 내장합니다. 각 모듈의 ArchUnit 테스트는 공통 규칙도 함께 지킵니다. 필드 주입 금지, 네이티브 SQL 금지, 엔터티가 API에 노출되지 않음, 모든 패키지의 기본 non-null 등입니다.

요청 하나의 처리 과정

sequenceDiagram
  participant B as 콘솔
  participant F as 필터 체인
  participant G as PermissionGuard
  participant C as 컨트롤러
  participant S as 도메인 서비스
  B->>F: 세션 Cookie + X-XSRF-TOKEN
  F->>F: 세션, CSRF, 테넌트 바인딩, 활동 기록
  F->>G: 로그인 완료
  G->>G: 계정의 권한 스냅샷을 읽어 인터페이스가 선언한 권한 코드 확인
  G->>C: 통과(응답에 X-Authorization-Version 포함)
  C->>S: 서비스를 호출하며 작업자 정보 전달
  S->>S: 데이터 범위, 필드 규칙, 업무 검증
  S-->>B: JSON 또는 RFC 9457 problem details

• 모든 컨트롤러 메서드는 접근 방식을 선언해야 합니다(공개, 로그인만 하면 사용 가능, 권한 코드 필요). 선언하지 않은 메서드가 있으면 서버가 시작되지 않습니다.
• 권한 코드는 동시에 API 리소스로도 등록되므로, 인터페이스의 권한 부여도 리소스 카탈로그에서 관리합니다.
• 오류는 모두 RFC 9457 problem details로 통일되며, 안정적인 code, 지역화된 detail, requestId를 포함합니다. 오류 코드를 참고하세요.

기술 선택