> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 플랫폼 아키텍처

> Iru Identity의 구축 방식: 데이터 상주, 안정성 및 관찰 가능성을 위해 설계된 격리된 리전 전반의 2-플레인 서비스 아키텍처입니다.

Iru Identity는 액세스의 신뢰할 수 있는 중심이 되도록 구축된 클라우드 서비스입니다. 아래에서는
서비스가 구축된 방식과 그것이 안정성 및 격리에 의미하는 바를 설명합니다.

## 역할별로 분리된 두 개의 플레인

플랫폼은 공통 계층형 코어를 공유하는 독립적으로 배포되는 두 개의 서비스로 나뉩니다. 권한 있는
프로비저닝을 테넌트별 요청 트래픽과 분리하면 각각의 영향 범위가 줄어듭니다.

```mermaid theme={null}
flowchart TB
  subgraph cp["컨트롤 플레인"]
    tprov["테넌트 수명 주기<br/>(생성 / 삭제)"]
    jwks["공개 키 게시(JWKS)"]
    tmpl["앱 템플릿 동기화"]
  end
  subgraph tp["테넌트 API"]
    iam["테넌트별 IAM API"]
    work["백그라운드 프로비저닝 워커"]
  end
  cp -->|"프로비저닝"| tp
  people["관리자 및 사용자"] --> tp
  apps["앱"] --> tp
```

| 플레인 | 책임 | 분리된 이유 |
| - | - | - |
| **컨트롤 플레인** | 테넌트 생성 및 삭제, 서명 키 게시, 애플리케이션 템플릿 카탈로그 동기화. | 고객 요청 트래픽과 분리된 작고 권한 있는 영역입니다. 테넌트 작업에는 상수 시간으로 비교되는 토큰이 필요하며, 템플릿 동기화 자격 증명은 요청마다 관리형 비밀 저장소에서 가져오므로 교체가 즉시 적용됩니다. |
| **테넌트 API** | 고객 대상 ID 및 액세스 API와 앱에 계정을 프로비저닝하는 백그라운드 워커. | 사용자와 앱이 실제로 사용하는 트래픽이 많은 영역으로, 프로비저닝은 대역 외로 처리되므로 느린 다운스트림 앱이 로그인을 차단하지 않습니다. |

## 체계적인 계층형 코어

두 서비스 모두 단방향 종속성 규칙이 있는 계층형 아키텍처로 Go에서 구축되었습니다. 별도로
적용되는 **platform** 계층은 제품 계층 아래에 위치하며 테넌트 격리 및 ID 기본 요소를
소유합니다. **foundation**은 테넌트 컨텍스트를 갖지 않는 공유 인프라 유틸리티를 위해 종속성
없이 유지됩니다.

<Steps>
  <Step title="플랫폼">
    테넌트 격리 및 ID 중추: 데이터베이스 액세스, 세션, 테넌트 및 리전 확인, 실행자, 로깅 및
    공개 URL 처리. 이 계층은 격리가 일반 제품 코드에 포함되지 않도록 별도로 검토되고 적용됩니다.
  </Step>

  <Step title="기반">
    상위 계층에 의존하지 않는 공유 인프라 유틸리티(예: 암호화 및 추적). 테넌트 범위 관련 사항은
    여기가 아닌 platform에 있습니다.
  </Step>

  <Step title="도메인">
    엔터티별 비즈니스 로직(사용자, 애플리케이션, 정책 등). platform과 foundation에 의존하며,
    usecase나 REST에는 의존하지 않습니다.
  </Step>

  <Step title="사용 사례">
    복잡한 흐름을 위해 여러 도메인 서비스를 조율합니다.
  </Step>

  <Step title="REST">
    HTTP 핸들러 및 미들웨어로, 네트워크 통신을 담당하는 유일한 계층입니다.
  </Step>
</Steps>

<Note>
  계층화는 컴파일러가 보장하는 불변 조건이 아니라 문서화되고 **검토를 통해 적용되는** 규칙입니다
  (린팅 및 디렉터리 구조로 뒷받침됨). 과장하지 않고 이를 정직하게 밝힙니다.
</Note>

테스트도 같은 원칙을 따릅니다. 순수 비즈니스 로직은 모의 객체 없이 단위 테스트되며, 동작은
**실제 PostgreSQL 데이터베이스에 대해 실행되는 통합 테스트**로 검증되므로, 테스트는 대체된
근사치가 아니라 프로덕션에서 실행되는 것과 동일한 행 수준 보안 및 감사 동작을 실행합니다.

## 호스팅 및 강화

Iru Identity는 보안이 강화된 배포로 **AWS**에서 실행됩니다.

<CardGroup cols={2}>
  <Card title="강화된 컨테이너" icon="cubes">
    서비스는 AWS Fargate에서 non-root로 실행되며 **읽기 전용 루트 파일 시스템**,
    **no-new-privileges**가 적용되고 모든 Linux 기능이 제거됩니다.
  </Card>

  <Card title="상시 데이터베이스 비밀번호 없음" icon="key">
    애플리케이션은 단기 **IAM 인증 토큰**을 사용하여 관리형 \*\*PostgreSQL(Amazon RDS)\*\*에
    연결합니다. 유출될 정적 DB 비밀번호가 없습니다.
  </Card>

  <Card title="비밀은 코드 외부에 유지" icon="vault">
    자격 증명과 서명 키는 런타임에 관리형 비밀 저장소에서 주입되며, 리포지토리에 커밋되거나
    데이터베이스에 일반 텍스트로 저장되지 않습니다.
  </Card>

  <Card title="스캔된 공급망" icon="magnifying-glass">
    컨테이너 이미지는 배포되기 전에 CI 파이프라인에서 취약점이 스캔됩니다.
  </Card>
</CardGroup>

정적 자산은 CDN(Fastly)을 통해 제공되며, 테스트용 단기 미리 보기 환경은 Google Cloud Run에서
실행됩니다.

## 두 개의 리전, 실제 데이터 상주

Iru Identity는 \*\*두 개의 격리된 리전(미국 `us-east-2` 및 유럽 연합 `eu-central-1`)\*\*에서
운영되며, 데이터 상주는 관례가 아닌 코드로 적용됩니다.

```mermaid theme={null}
flowchart LR
  req["요청"] --> mw["하위 도메인에서<br/>테넌트 확인"]
  mw --> reg{"테넌트의<br/>리전?"}
  reg -->|"US"| usdb[("US 데이터베이스")]
  reg -->|"EU"| eudb[("EU 데이터베이스")]
  reg -->|"알 수 없음"| rej["거부됨"]
```

* 모든 테넌트는 테넌트 레코드에 저장된 **리전에 고정**됩니다.
* 데이터베이스 계층은 **리전별로 별도의 연결 풀**을 보유하고 모든 트랜잭션을 테넌트의 리전에
  따라 라우팅합니다. 리전을 확인할 수 없는 요청은 **거부됩니다**. 다른 리전으로 조용히 대체되지
  않습니다.
* 리전별 데이터 작업(예: 시드 데이터)은 잘못된 리전에 대해 실행되지 않도록 제한됩니다.

결과적으로 EU 테넌트의 데이터는 EU 인프라에서만 읽고 쓰여집니다. 각 리전 데이터베이스 *내부*에서
격리가 계속되는 방식은 [멀티 테넌트 격리](/ko/identity/security/multi-tenant-isolation)를
참조하세요.

## 가동 상태 유지 및 관찰 가능성을 위한 설계

<AccordionGroup>
  <Accordion title="상태 검사 및 정상 종료" icon="heart-pulse">
    종속성 없는 활성 상태 엔드포인트를 통해 오케스트레이터가 데이터베이스나 인증을 건드리지 않고
    검사할 수 있습니다. 종료 시 서비스는 트래픽 수락을 중지하고 추적, 오류 보고 및 데이터베이스
    연결을 순서대로 플러시합니다.
  </Accordion>

  <Accordion title="탄력적인 데이터 액세스" icon="database">
    연결 풀은 조정되고 제한되며, 시작 시 데이터베이스에 ping을 보내고, 연결할 수 없는 경우 손상된
    요청을 처리하는 대신 **빠르게 실패**합니다.
  </Accordion>

  <Accordion title="최종 일관성 프로비저닝" icon="arrows-rotate">
    앱에 대한 계정 프로비저닝은 취소를 인식하는 백그라운드 워커의 **아웃박스 및 조정** 루프를 통해
    실행되므로, 다운스트림 변경 사항이 손실되지 않고 성공할 때까지 재시도됩니다.
  </Accordion>

  <Accordion title="엔드투엔드 추적" icon="diagram-project">
    요청은 HTTP부터 애플리케이션 코드를 거쳐 SQL 쿼리까지 **OpenTelemetry**로 추적되며, 구조화된
    로그는 테넌트 및 추적 ID로 상관 관계가 지정됩니다. 오류는 충실도와 비용의 균형을 맞추기 위해
    샘플링과 함께 중앙에서 캡처됩니다.
  </Accordion>

  <Accordion title="검증 가능한 마이그레이션 및 감사" icon="file-shield">
    스키마 변경은 포함되고, 버전 순서가 지정되며, **체크섬으로 검증됩니다**(이미 적용된
    마이그레이션이 변경되면 즉시 실패). 상시 검사기가 모든 테이블의 감사 저널이 라이브 스키마와
    동기화된 상태로 유지되는지 증명합니다.
  </Accordion>
</AccordionGroup>

## 다음 단계

<CardGroup cols={2}>
  <Card title="멀티 테넌트 격리" icon="database" href="/ko/identity/security/multi-tenant-isolation">
    행 수준 보안과 추가 전용 감사가 모든 테넌트의 데이터를 분리하고 변조 감지 가능하게 유지하는
    방식입니다.
  </Card>

  <Card title="인증 아키텍처" icon="signature" href="/ko/identity/security/authentication-architecture">
    피싱 방지 로그인, 서명된 요청 및 SSO 신뢰가 구축되는 방식입니다.
  </Card>

  <Card title="보안 및 개인정보 보호" icon="lock" href="/ko/identity/security/security-and-privacy">
    이러한 메커니즘이 제공하는 보장입니다.
  </Card>

  <Card title="시스템 아키텍처" icon="sitemap" href="/ko/identity/getting-started/system-architecture">
    ID 및 로그인 흐름에 대한 고객 관점의 보기입니다.
  </Card>
</CardGroup>