architecture system

시스템 아키텍처

ADR 0035에서 확정한 대표 다이어그램(agiespi_architecture_overview_final1.drawio, agiespi_architecture_overview_final3.drawio.png)과 현재 Terraform/운영 기준으로 Aegis-Pi 전체 시스템을 Factory Spoke, AWS managed/global services, Control / Management VPC, Data / Dashboard VPC로 나누어 설명한다.

---

전체 구획

현재 목표 구조는 네 영역을 분리한다.

Factory Spokes
  - factory-a: Raspberry Pi 3-node K3s 운영형 Spoke
  - factory-b: Mac mini VM K3s 테스트베드
  - factory-c: Windows VM K3s 테스트베드

AWS managed / global services
  - Cognito Hosted UI / Admin API
  - Route 53 DNS
  - CloudFront (+ WAF/IP 제한은 선택·계획 구성)
  - S3 SPA dashboard-web
  - AWS IoT Core MQTT / Rules
  - DynamoDB LATEST / HISTORY / GRAPH / CloudInfra Streams
  - Lambda data processor, report generator, CloudInfra collectors
  - S3 data raw / processed / reports

Control / Management VPC (10.0.0.0/16)
  - EKS Hub
  - Hub ArgoCD
  - Tailscale Connector / Operator
  - Grafana
  - AWS Load Balancer Controller

Data / Dashboard VPC (10.20.0.0/16 기준)
  - ALB HTTPS api.<도메인>
  - ECS Fargate Backend
  - Lambda notifier
  - ElastiCache Redis
  - RDS PostgreSQL

Control / Management VPC는 배포와 운영 제어를 담당하고, Data / Dashboard VPC는 사용자 API와 대시보드 read path를 담당한다. 두 VPC는 직접 연결하지 않는다. Dashboard는 K3s, EKS, ArgoCD, Tailscale 관리 API를 직접 읽지 않고 DynamoDB, S3 processed/reports, RDS, Redis 같은 데이터 저장소와 캐시만 사용한다.

대표 이미지의 Data / Dashboard VPC CIDR 표기는 논리 예시다. 현재 Terraform 기준은 infra/data-dashboard/variables.tf의 10.20.0.0/16이며, Hub VPC 10.0.0.0/16과 겹치지 않는다는 점이 운영 기준이다.

---

대표 이미지 기준 구조

Browser / 본사 관제 사용자
  -> DNS / Cognito / CloudFront / S3 SPA
  -> ALB HTTPS api.<도메인>
  -> ECS Fargate Backend
  -> DynamoDB / S3 / RDS / Redis

Dev & Build
  -> GitHub Actions
  -> ECR
  -> Hub ArgoCD
  -> Tailscale
  -> Factory K3s API

Factory Spokes
  -> MQTT Telemetry (mTLS over Public Internet)
  -> AWS IoT Core
  -> Lambda data processor
  -> DynamoDB / S3 processed
  -> Dashboard Backend read

factory-a는 실제 Raspberry Pi K3s 3-node 운영형 Spoke다. factory-b/c는 멀티 Spoke 배포, topic/prefix 분리, 지연시간, Dashboard 카드 분리를 검증하는 VM 테스트베드이며 실제 센서 정확도 검증 환경으로 보지 않는다.

---

색상별 흐름

대표 이미지의 선 색상은 역할 경계를 나타낸다.

색상	흐름	설명
초록 실선	MQTT 데이터 적재	Edge Agent 또는 dummy generator가 MQTT mTLS로 AWS IoT Core 공개 endpoint에 telemetry를 송신한다. IoT Rule과 Lambda data processor가 DynamoDB LATEST/HISTORY/GRAPH와 S3 raw/processed를 갱신한다.
초록 점선	보고서 / 파생 데이터	S3 data raw/processed/reports와 Bedrock 기반 report generator, CloudInfra read model 갱신처럼 사용자 화면의 파생 데이터를 만드는 경로다.
파랑 실선	사용자 / API	Browser가 CloudFront SPA와 ALB 뒤 ECS Backend를 사용한다. API는 Cognito JWT를 검증하고 DynamoDB/S3/RDS/Redis를 조회한다.
파랑 점선	인증 / OIDC / MFA	Browser가 Cognito Hosted UI로 로그인하고 JWT를 받아 SPA와 Backend 호출에 사용한다. GitHub Actions의 S3/CloudFront invalidation OIDC도 이 계열로 표현된다.
주황 실선	WebSocket push	DynamoDB Streams가 Lambda notifier를 호출하고, notifier가 Redis Pub/Sub에 publish하면 ECS Backend가 WebSocket으로 브라우저에 변경을 push한다.
보라 실선 / 점선	배포 / 제어	GitHub Actions가 ECR에 이미지를 push하고, Hub ArgoCD가 Tailscale을 통해 각 Factory K3s API에 GitOps sync를 수행한다.
회색 점선	조회 / read path	Dashboard Backend가 DynamoDB, S3, RDS, Redis 같은 read model과 메타데이터를 조회한다. 관리 API 직접 조회가 아니다.
빨강 X	VPC 직접 연결 없음	Control / Management VPC와 Data / Dashboard VPC 사이에 VPC peering 또는 Transit Gateway 같은 직접 네트워크 연결을 두지 않는다.

---

제어 경로

배포와 운영 제어는 Control / Management VPC의 EKS Hub가 담당한다.

GitHub
  -> GitHub Actions
  -> Amazon ECR
  -> Git manifest / Helm values
  -> Hub ArgoCD (EKS)
  -> Tailscale Connector
  -> factory-a/b/c K3s API
  -> workload rollout

Hub ArgoCD는 각 factory의 cluster Secret과 ApplicationSet을 기준으로 Spoke workload를 배포한다. factory-a에는 기존 local ArgoCD가 남아 있을 수 있지만, 신규 edge data-plane과 멀티 factory 배포의 목표 지점은 Hub ArgoCD다.

---

데이터 경로

데이터는 Tailscale을 거치지 않는다.

factory-a/b/c
  -> edge-iot-publisher / dummy-data-generator
  -> MQTT mTLS over Public Internet
  -> AWS IoT Core / Rules
  -> Lambda data processor
  -> DynamoDB LATEST / HISTORY#STATE / GRAPH#5M / CLOUD#infra
  -> S3 raw / processed / processed_agg / reports
  -> Dashboard Backend read

S3 raw는 원본 보존, 재처리, 감사, 보고서 입력으로 사용한다. Dashboard의 현재 상태와 그래프는 DynamoDB read model과 S3 processed/reports를 우선 사용한다.

---

사용자/API 경로

사용자는 Tailscale이나 Hub EKS에 접속하지 않는다.

Browser
  -> Route 53
  -> CloudFront (+ optional/planned WAF)
  -> S3 SPA dashboard-web
  -> Cognito Hosted UI
  -> ALB HTTPS api.<도메인>
  -> ECS Fargate Backend
  -> DynamoDB / S3 / RDS / Redis

Backend는 Cognito JWT를 앱 레벨에서 검증한다. 사용자와 공장 권한은 RDS PostgreSQL 메타데이터(app_user, user_factory_access, factory, audit_log)를 기준으로 필터링한다.

---

Active / Optional / Retired

상태	구성
Active	Factory A K3s, Factory B/C VM Spoke, IoT Core, Lambda data processor, DynamoDB read model, S3 raw/processed/reports, Data / Dashboard VPC, ECS Fargate Backend, RDS PostgreSQL, Redis, Cognito, CloudFront, Hub EKS, ArgoCD, Tailscale Operator, Grafana, AWS Load Balancer Controller
Optional / On-demand	Admin UI ALB, Tailscale 기반 ArgoCD/Grafana UI Service, Bedrock report generator on-demand stack, WAF/IP 제한 강화
Retired / 과거 이력	AMP, Hub Prometheus Agent, Hub risk-normalizer 파드 기반 Risk 계산

---

관련 문서

• 제어 플레인 & 데이터 플레인
• 하드웨어 배치 & 인프라 구성
• Hub EKS 네임스페이스
• Tailscale Mesh VPN
• Dashboard VPC 설계
• 데이터 생명주기