architecture realtime update

Dashboard 실시간 갱신 구조

Dashboard 상태 갱신은 DynamoDB read model, DynamoDB Streams, Lambda notifier, Redis Pub/Sub, WebSocket, REST fallback을 조합한 준실시간 구조다.

---

전체 흐름

IoT / collector / processor
  -> DynamoDB AEGIS-DynamoDB-FactoryStatus
      pk=FACTORY#{factory_id}, sk=LATEST
      pk=FACTORY#{factory_id}, sk=HISTORY#STATE#{timestamp}
      pk=FACTORY#{factory_id}, sk=GRAPH#5M#{bucket}
  -> DynamoDB Streams
  -> Lambda notifier
  -> Redis PUBLISH factory:update:{factory_id}
  -> FastAPI WebSocket subscribe
  -> Browser refresh/render

이 경로는 화면 갱신 신호를 빠르게 전달하기 위한 관제 경로다. 장비 제어, 배포, 복구 명령을 전달하지 않는다.

---

LATEST 갱신

공장별 최신 상태의 source of truth는 DynamoDB AEGIS-DynamoDB-FactoryStatus의 LATEST item이다.

pk = FACTORY#{factory_id}
sk = LATEST

LATEST에는 factory_state, infra_state, risk, pipeline_status, updated_at 등이 들어간다. Backend의 /factories/{factory_id}는 이 item을 그대로 반환하고, /factories는 여러 공장의 LATEST를 요약해 반환한다.

Cloud/System 상태는 같은 table의 별도 key를 사용한다.

pk = CLOUD#infra
sk = LATEST

---

DynamoDB Streams

Lambda notifier는 DynamoDB Streams event source mapping으로 연결된다. event source는 AEGIS-DynamoDB-FactoryStatus stream ARN이며, Lambda는 INSERT와 MODIFY record만 처리한다.

처리 조건:

조건	동작
eventSource != aws:dynamodb	skip
eventName이 INSERT/MODIFY가 아님	skip
NewImage 없음	skip
sk != LATEST	skip
pk=FACTORY#{factory_id}	factory ID 추출 후 publish

즉, notifier는 history/graph item을 publish하지 않고 공장별 LATEST 변경만 WebSocket 갱신 신호로 사용한다.

---

Lambda Notifier

apps/lambda-notifier/lambda_function.py는 stream record의 NewImage를 DynamoDB type deserializer로 JSON 변환한 뒤 Redis channel에 publish한다.

channel = factory:update:{factory_id}
payload = deserialized LATEST item JSON

Lambda는 private-app subnet에 VPC attach되고 Redis security group에 접근한다. Redis AUTH token은 Secrets Manager에서 읽으며 Redis client와 secret lookup은 warm invocation 간 캐시된다.

실패한 stream batch는 lambda_notifier.tf의 SQS DLQ destination으로 보낸다.

---

Redis Pub/Sub

ElastiCache Redis는 Dashboard의 push fan-out 계층이다.

항목	현재 설정
Engine	Redis 7.1
Node	cache.t4g.micro, single node
TLS	in-transit encryption enabled
Auth	AUTH token enabled
Multi-AZ	false
Automatic failover	false

Redis는 source of truth가 아니다. WebSocket push 신호가 유실되면 REST refresh가 최종 데이터를 다시 읽는다.

---

WebSocket

Backend endpoint:

WS /ws/factories/{factory_id}?token=<JWT>

동작:

1. verify_ws_token()으로 Cognito JWT를 검증한다.
2. RDS metadata로 principal을 만든다.
3. can_access_factory(principal, factory_id)로 공장 권한을 확인한다.
4. Redis factory:update:{factory_id} channel을 subscribe한다.
5. Redis message payload를 WebSocket text frame으로 browser에 전달한다.

Close code:

Code	의미
4001	token 검증 실패
4003	공장 접근 권한 없음
1011	Redis subscribe/polling 등 서버 내부 오류

WebSocket payload는 최신 item의 push 신호다. 클라이언트는 이를 화면 갱신 트리거로 사용하고, 필요하면 REST를 다시 호출해 정합성을 맞춘다.

---

REST Refresh Fallback

Dashboard는 WebSocket이 없거나 끊겨도 REST polling으로 동작해야 한다.

화면	REST fallback
Fleet/공장 목록	GET /factories
공장 상세 latest	GET /factories/{factory_id}
공장 history chart/timeline	GET /factories/{factory_id}/history?window=...
Cloud infra	GET /cloud-infra, GET /cloud-infra/history
Report	GET /reports, GET /reports/{date}/{factory_id}

Redis/WebSocket은 빠른 알림 경로이고, DynamoDB/S3 REST 조회가 최종 read path다.

---

History Delta Refresh

GET /factories/{factory_id}/history는 since query를 지원한다.

GET /factories/factory-a/history?window=1h&since=2026-06-08T01:02:03.000Z

Backend 동작:

Window	Query
<=1h	DynamoDB HISTORY#STATE#{since} 이상 raw snapshot
>1h	DynamoDB GRAPH#5M#{since} 이상 aggregate bucket

since가 있으면 Backend가 추출 결과에서 timestamp > since인 item만 반환한다. UI는 기존 series에 신규분을 merge/dedupe하여 전체 구간 재조회 비용을 줄인다.

기본 limit:

Window	기본 limit
10m	250
1h	2000
기타	500

---

Staleness 판단

준실시간 관제에서 중요한 것은 "값이 최신인지"를 표시하는 것이다. LATEST item의 updated_at, factory_state.source_timestamp, infra_state.source_timestamp, pipeline_status.status를 함께 본다.

상태	의미
정상	최근 telemetry와 infra 상태가 허용 지연 안에 갱신됨
warning	수집/집계 지연이 커져 화면 값이 stale해질 가능성 있음
critical	최신 상태가 오래 갱신되지 않아 현재 상태로 단정하면 안 됨

문서상 목표 반영 지연은 초 단위 준실시간 관제 기준이다. 제어 명령의 실시간 보장이나 exactly-once 전달 보장이 아니다.

---

실패 모드와 복구

실패 지점	화면 영향	복구/완화
Lambda notifier 실패	WebSocket push 지연/누락	DLQ 확인, REST polling fallback
Redis 장애	WebSocket close 1011, push 중단	REST polling fallback, /readyz redis failed
DynamoDB timeout	REST 504, readyz degraded	DDB timeout/concurrency 제한, warmup, history limit
RDS metadata 장애	인증 후 권한 확인 실패, readyz degraded	/readyz rds_metadata 확인
S3 장애	reports 504	report 조회만 영향

---

준실시간 관제와 실시간 제어의 분리

WebSocket이 있어도 이 구조는 제어 채널이 아니다. Dashboard Backend는 Redis subscribe와 DynamoDB/S3/RDS read/write metadata만 수행한다. 설비 제어, 배포, K3s/ArgoCD 조작은 Control/Management plane에서 별도 인증·감사·승인 경로로 다뤄야 한다.