HAI Agents RRS

hai-agents: 프로젝트 분석 및 요약 보고서

1. 프로젝트 개요

2. 프로젝트 구조 (Project Structure Analysis)

• infra/: SST(Serverless Stack) 프레임워크를 사용한 인프라 코드(IaC)가 위치합니다. AWS 리소스(API 게이트웨이, S3, Lambda 등), 도메인, CI/CD 설정 등 애플리케이션 실행에 필요한 모든 인프라를 코드로 정의합니다.

• packages/: 애플리케이션의 핵심 로직과 기능을 담당하는 여러 하위 패키지로 구성됩니다.
• core/: Asset, Criteria 등 핵심 데이터 모델과 비즈니스 로직이 정의된 가장 중요한 패키지입니다.
• functions/: tRPC를 사용한 API 백엔드 람다 함수들이 위치합니다. core 패키지의 로직을 사용하여 실제 API 요청을 처리합니다.
• web/: Vite 기반의 프론트엔드 SPA(Single Page Application)입니다. 사용자 인터페이스를 제공합니다.
• shared/: 프론트엔드와 백엔드 간에 공유되는 타입 정의, 유효성 검사 스키마 등이 위치합니다.
• repo_risk_eval/, clustering/ 등: 특정 분석 작업을 수행하는 독립적인 워커(worker) 패키지들입니다.

3. Prismatic Ranked Recursive Summarization

3.1. 아키텍처 뷰 (Architectural View)

• 서버리스 아키텍처: AWS Lambda, API Gateway, S3, Cognito 등 완전 관리형 서버리스 서비스를 기반으로 설계되어 확장성과 유지보수성이 뛰어납니다.

• 모듈화된 인프라: infra/ 디렉토리 내에 api.ts, storage.ts, frontend.ts 등 기능별로 인프라 코드가 모듈화되어 있어 구성이 명확합니다.

• tRPC 기반 API: API는 tRPC를 사용하여 타입-세이프(type-safe)한 방식으로 프론트엔드와 백엔드 간의 통신을 보장합니다.

• 광범위한 외부 서비스 연동: Azure OpenAI, Google Generative AI, Hugging Face 등 다수의 AI/ML 플랫폼과 Confluence, GitHub, Slack 등 협업 도구를 적극적으로 활용합니다.

graph TD;
    subgraph "사용자"
        A["프론트엔드 (Web UI)"];
    end

    subgraph "AWS 클라우드 (서버리스)"
        B["API Gateway (tRPC)"];
        C["인증 (Cognito & WorkOS)"];
        D["백엔드 로직 (AWS Lambda)"];
        E["데이터 저장소 (S3 버킷)"];
        F["이벤트 버스 (EventBridge)"];
        G["데이터베이스 (Postgres)"];
    end

    subgraph "외부 서비스"
        H["AI/ML 분석 서비스<br/>(Azure, Google 등)"];
        I["서드파티 앱<br/>(GitHub, Slack 등)"];
    end

    A -- "API 요청" --> B;
    B -- "인증" --> C;
    B -- "라우팅" --> D;
    D -- "비동기 작업 트리거" --> F;
    D -- "데이터 CRUD" --> G;
    D -- "분석 요청" --> H;
    D -- "연동" --> I;
    F -- "비동기 작업 수행" --> D;
    D -- "결과 저장" --> E;
    E -- "결과 조회" --> D;

3.2. 데이터 흐름 뷰 (Data Flow View)

1. 시작: 사용자가 프론트엔드 UI를 통해 '자산(Asset)'을 생성하거나 평가를 시작하면, tRPC API를 통해 백엔드에 요청이 전송됩니다.

2. 처리 요청: 백엔드(asset.ts 라우터)는 요청을 받아 데이터베이스에 상태를 기록하고, 비동기 처리를 위해 이벤트 버스로 메시지를 보냅니다.

3. 비동기 분석: 이벤트 버스의 메시지를 구독하는 람다 함수(평가 엔진)가 트리거됩니다. 이 엔진은 자산에 설정된 '기준(Criteria)'에 따라 필요한 외부 AI/ML 서비스에 분석을 요청합니다.

4. 결과 저장: 외부 서비스로부터 받은 분석 결과는 S3 버킷(CriteriaResultBucket 등)에 저장되고, 처리 상태는 데이터베이스에 업데이트됩니다.

5. 결과 조회: 사용자는 프론트엔드에서 분석 결과를 조회하며, 이 요청은 S3 버킷이나 데이터베이스에 저장된 데이터를 읽어와 사용자에게 보여줍니다.

3.3. 보안 뷰 (Security View)

• 중앙화된 비밀 관리: 모든 API 키, 외부 서비스 비밀 정보는 infra/secrets.ts 파일에서 sst.Secret을 통해 중앙에서 안전하게 관리됩니다. 소스 코드에 민감한 정보가 하드코딩되어 있지 않아 보안성이 높습니다.

• 이중 인증 전략: 일반 사용자를 위한 AWS Cognito 인증과 기업용 SSO(Single Sign-On)를 위한 WorkOS 기반의 JWT 인증, 두 가지 방식을 모두 지원합니다. 이는 다양한 고객층을 고려한 유연한 인증 체계입니다.

• API 접근 제어: API의 모든 경로는 WorkOS JWT Authorizer에 의해 보호되어, 인가된 사용자만이 API에 접근할 수 있습니다.

• OAuth 처리: 프론트엔드는 서드파티 서비스(GitHub, Confluence 등)와의 연동을 위한 OAuth 인증 흐름을 직접 처리하는 데 필요한 클라이언트 ID와 인증 URL을 백엔드로부터 안전하게 전달받습니다.

4. 결론