BaronSSO/baron-sso/docs/baronsso_structure_analysis.md

# Baron SSO 구조 분석

## 1. 이 시스템은 무엇인가

Baron SSO는 계열사 또는 화이트라벨 대상 서비스들의 로그인, 권한, 애플리케이션 연동을 중앙에서 관리하는 통합 인증/인가 허브입니다. 저장소의 설명과 구성 파일을 보면 단순 로그인 화면이 아니라 다음 역할을 함께 수행하는 IAM 플랫폼에 가깝습니다.

- 사용자 인증과 계정 수명주기 관리
- OAuth2/OIDC 기반 SSO와 RP(Relying Party) 연동
- 권한 정책 및 접근 제어 관리
- 관리자용 운영 화면, 개발자용 RP 관리 화면, 조직도/조직 컨텍스트 화면 제공
- 감사 로그 수집과 운영 데이터 관리

핵심적으로는 Ory Stack을 자체 호스팅하고, Baron Backend가 비즈니스 규칙과 운영 기능을 담당하며, 여러 프론트엔드가 역할별 UI를 제공합니다.

## 2. 전체 아키텍처 요약

현재 저장소는 하나의 애플리케이션이 아니라, 인증 인프라와 여러 사용자 인터페이스를 함께 운영하는 멀티 서비스 구조입니다.

### 2.1 주요 계층

1. Ory 기반 IAM 계층
2. Baron 자체 백엔드 계층
3. 역할별 프론트엔드 계층
4. 게이트웨이 및 인프라 계층
5. 데이터 저장소 및 로깅 계층

### 2.2 구성 요소별 역할

#### Ory Stack

`compose.ory.yaml` 기준으로 다음 컴포넌트를 별도 컨테이너로 운영합니다.

- Kratos: 사용자 인증, 계정, self-service flow
- Hydra: OAuth2/OIDC 서버, 로그인/동의 흐름, 토큰 발급
- Keto: 권한 관계 및 정책 기반 접근 제어
- Oathkeeper: 프록시형 접근 제어 게이트

즉, Baron SSO의 인증/인가 핵심은 Ory를 기반으로 하고, Baron 코드는 그 위에서 비즈니스 로직과 운영 기능을 덧씌우는 구조입니다.

#### Backend

`backend`는 Go Fiber 기반 API 서버이며, 저장소 README 설명대로 Ory Stack과 여러 프론트엔드 사이의 주된 비즈니스 백엔드 역할을 수행합니다.

역할은 다음과 같이 해석할 수 있습니다.

- 프론트엔드가 호출하는 자체 API 제공
- Ory Admin/Public API와 연동하여 로그인, 동의, RP 관련 흐름 제어
- 감사 로그 적재
- 테넌트, 사용자, 운영 데이터 처리
- 외부 연동 기능 처리

`docker-compose.yaml`에서도 각 웹 프론트엔드가 `API_PROXY_TARGET=http://baron_backend:3000`으로 이 백엔드를 바라보도록 구성되어 있습니다.

#### 프론트엔드 계층

역할이 나뉜 여러 UI가 함께 존재합니다.

- `userfront`: 최종 사용자용 로그인/인증 UI, Flutter 기반
- `adminfront`: 관리자용 운영 UI, React/Vite 기반
- `devfront`: 개발자용 RP 및 연동 관리 UI, React/Vite 기반
- `orgfront`: 조직/컨텍스트 시각화 및 관리 성격의 UI, React/Vite 기반

프론트엔드가 분리되어 있다는 점은 이 시스템이 단일 로그인 페이지 수준이 아니라, 사용자 포털과 운영 포털을 함께 포함하는 플랫폼임을 보여줍니다.

#### Gateway

`gateway`는 Nginx 기반 컨테이너이며 외부 진입점 역할을 담당합니다. `compose.infra.yaml`에서 `public_net`에 연결되어 있고, `USERFRONT_PORT`를 외부로 노출합니다. 따라서 사용자가 처음 접근하는 표면은 게이트웨이 또는 Oathkeeper를 포함한 프록시 계층을 통해 노출되는 구조로 볼 수 있습니다.

#### 데이터 및 부가 인프라

저장소에는 인증 인프라용 저장소와 서비스 메타데이터용 저장소가 분리되어 있습니다.

- PostgreSQL: Baron 메타데이터 저장 및 Ory 데이터 저장소
- ClickHouse: 감사 로그 및 이벤트성 데이터 적재
- Redis: 캐시/세션성 또는 보조 저장소 용도
- Promtail, Blackbox Exporter, Vector: 로그/모니터링/전송 보조 구성

### 2.3 구조도

```mermaid
flowchart LR
    User[User / Admin / Developer] --> Gateway[Nginx Gateway / Public Entry]
    User --> WebApps[Frontends]

    subgraph Frontend Layer
      UF[userfront\nFlutter]
      AF[adminfront\nReact + Vite]
      DF[devfront\nReact + Vite]
      OF[orgfront\nReact + Vite]
    end

    Gateway --> UF
    AF --> BE
    DF --> BE
    OF --> BE
    UF --> BE

    subgraph Service Layer
      BE[Baron Backend\nGo + Fiber]
    end

    subgraph IAM Layer
      KR[Ory Kratos]
      HY[Ory Hydra]
      KE[Ory Keto]
      OK[Ory Oathkeeper]
    end

    BE --> KR
    BE --> HY
    BE --> KE
    OK --> KR
    OK --> HY
    OK --> KE

    subgraph Data Layer
      PG[(PostgreSQL)]
      CH[(ClickHouse)]
      RD[(Redis)]
    end

    BE --> PG
    BE --> CH
    BE --> RD
    KR --> PG
    HY --> PG
    KE --> PG
```

## 3. 개발 기술 스택 정리

### 3.1 백엔드

- Language: Go 1.26.2
- Web Framework: Fiber v2
- ORM/DB access: GORM, PostgreSQL driver, `lib/pq`
- IAM/OIDC 관련: `coreos/go-oidc`, `golang.org/x/oauth2`, `go-jose`
- Cache/infra: Redis, ClickHouse
- Test: Testify, Testcontainers
- 기타 연동: AWS SDK v2, SES

즉, 백엔드는 Go 기반의 API 서버이면서 IAM 흐름을 직접 제어하는 오케스트레이션 계층입니다.

### 3.2 사용자 프론트엔드

`userfront/pubspec.yaml` 기준 스택은 다음과 같습니다.

- Framework: Flutter
- Language runtime: Dart SDK 3.10+
- State management: Riverpod
- Routing: go_router
- 기타: easy_localization, qr_flutter, mobile_scanner, shared_preferences

이를 보면 `userfront`는 웹 중심 React 앱이 아니라 Flutter 기반의 사용자 인증 UI이며, QR 로그인, 다국어, 로컬 상태 저장 등의 기능을 염두에 둔 구조입니다.

### 3.3 운영/관리 프론트엔드

`adminfront`, `devfront`, `orgfront`는 공통적으로 현대적인 React 프론트엔드 스택을 사용합니다.

- Framework: React 19
- Build tool: Vite 8
- Language: TypeScript 6
- Styling: Tailwind CSS, tailwindcss-animate
- UI primitives: Radix UI
- Data fetching/cache: TanStack Query
- Form/validation: react-hook-form, zod
- Auth client: oidc-client-ts, react-oidc-context
- HTTP client: axios
- Test: Vitest, Playwright
- Lint/format: Biome

`orgfront`는 여기에 `@xyflow/react`를 사용하고 있어 조직 구조나 컨텍스트 시각화 성격의 기능이 포함된 것으로 보입니다.

### 3.4 공통/모노레포 구성

- Package manager: pnpm workspace
- 공통 패키지: `common`
- 공통 리소스: `locales`
- 코드 품질: Biome

즉, 프론트엔드는 모노레포 형태로 운영되며 공통 UI/설정/로케일 자산을 공유합니다.

### 3.5 인프라 및 배포

- Container orchestration: Docker Compose
- Reverse proxy: Nginx
- IAM platform: Ory Kratos, Hydra, Keto, Oathkeeper
- Database: PostgreSQL
- Analytics/Audit store: ClickHouse
- Cache: Redis
- Observability: Promtail, Vector, Blackbox Exporter

## 4. 이 저장소에서 보이는 설계 특징

### 4.1 멀티테넌트 운영 시스템 성격

README와 `seed-tenant.csv`, 테넌트 import/export 관련 문서 이름들로 보아 이 시스템은 단일 서비스용 로그인 서버가 아니라, 여러 조직과 테넌트를 관리하는 멀티테넌트 IAM 운영 시스템입니다.

### 4.2 인증과 운영 기능의 분리

인증 그 자체는 Ory Stack이 맡고, Baron Backend와 각 Frontend가 다음을 담당합니다.

- 비즈니스 규칙 적용
- 운영 UI 제공
- 테넌트/사용자 관리
- RP 등록 및 OIDC 연동 관리
- 감사 로그와 운영성 기능

이 구조는 범용 IAM 엔진과 도메인 특화 운영 시스템을 분리한 설계로 볼 수 있습니다.

### 4.3 감사와 추적 가능성을 중시

ClickHouse, Promtail, Vector, 감사 로그 관련 README 설명을 보면 운영 추적성과 감사 가능성을 중요한 요구사항으로 두고 있습니다. 특히 로그인/권한/관리자 작업의 추적을 고려한 구조로 해석됩니다.

### 4.4 역할별 UI 분리

최종 사용자, 운영 관리자, 개발자, 조직 관리 성격의 UI가 분리되어 있어 권한과 업무 맥락에 따라 화면을 구분하는 B2B 운영 시스템의 전형적인 구조를 가집니다.

## 5. 한 줄 요약

Baron SSO는 Ory Stack을 자체 호스팅 기반으로 사용하면서, Go 백엔드와 여러 역할별 프론트엔드를 결합해 구성한 멀티테넌트 SSO/IAM 운영 플랫폼입니다. 기술적으로는 Go + Fiber, Flutter, React + Vite + TypeScript, PostgreSQL, ClickHouse, Redis, Docker Compose, Ory 생태계를 중심으로 구성되어 있습니다.

## 6. 분석 시 참고한 주요 근거 파일

- `README.md`
- `docker-compose.yaml`
- `compose.infra.yaml`
- `compose.ory.yaml`
- `backend/go.mod`
- `adminfront/package.json`
- `devfront/package.json`
- `orgfront/package.json`
- `userfront/pubspec.yaml`
- `pnpm-workspace.yaml`

## 7. 주의사항

루트 README의 일부 프로젝트 구조 설명은 현재 저장소의 실제 구성과 완전히 일치하지 않을 수 있습니다. 예를 들어 `adminfront`, `devfront`, `orgfront`는 실제로 React/Vite 기반 패키지이고, `userfront`는 별도의 Flutter 애플리케이션입니다. 따라서 현재 구조 분석은 README 서술보다 실제 매니페스트와 compose 파일을 우선 기준으로 정리했습니다.