component dashboard backend

Dashboard Backend 컴포넌트

apps/dashboard-backend FastAPI Backend의 실행 위치, API surface, 저장소 의존성, readiness 기준을 정리한다.

---

실행 위치

Dashboard Backend는 infra/data-dashboard/ecs.tf에서 ECS Fargate service로 실행된다.

항목	현재 구현
Runtime	FastAPI, container port 8000
배치	private-app subnet, assign_public_ip=false
진입	internet-facing ALB HTTPS -> Target Group HTTP 8000
Health check	ALB/ECS 모두 /healthz
Logs	CloudWatch Logs /ecs/<prefix>-backend
Secret injection	Secrets Manager DATABASE_URL, REDIS_URL

Task role은 DynamoDB FactoryStatus read, S3 processed/reports/image_snapshot read, Secrets Manager read, Cognito user admin 일부 권한을 가진다. Control/Management VPC의 EKS, ArgoCD, Spoke K3s API 권한은 포함하지 않는다.

---

Router와 Endpoint

main.py는 다음 router를 include한다.

Router	Prefix/Path	역할
routers.factories	/factories	공장 latest, summary, history
routers.cloud_infra	/cloud-infra	cloud/system read model
routers.reports	/reports	S3 Markdown report 목록/본문
routers.image_snapshots	/image-snapshots	S3 image snapshot 목록과 presigned GET
routers.admin_users	/admin/users	사용자/RBAC 관리
routers.auth_me	/auth/me	현재 principal 조회
routers.ws	/ws/factories/{factory_id}	Redis Pub/Sub WebSocket bridge

실제 decorator 기준 endpoint 목록:

Method	Path	인증/인가	주 저장소
GET	/healthz	없음	없음
GET	/readyz	없음	DynamoDB, Redis, RDS probe
GET	/factories	Cognito JWT	DynamoDB LATEST, 10초 in-process cache
GET	/factories/{factory_id}	공장 접근 권한	DynamoDB pk=FACTORY#{factory_id}, sk=LATEST
GET	/factories/{factory_id}/history	공장 접근 권한	DynamoDB HISTORY#STATE# 또는 GRAPH#5M#
GET	/cloud-infra	system view 권한	DynamoDB pk=CLOUD#infra, sk=LATEST
GET	/cloud-infra/history	system view 권한	DynamoDB HISTORY#FAST#/HISTORY#SLOW#
GET	/reports	공장/system 권한별 필터	S3 reports/daily/
GET	/reports/{report_date}/{factory_id}	공장 또는 system 권한	S3 report Markdown
GET	/image-snapshots/range	system view 권한	S3 image_snapshot/ partition 범위
GET	/image-snapshots	system view 권한	S3 image 목록 + presigned GET
GET	/admin/users	user admin 권한	RDS metadata
POST	/admin/users	user admin 권한	Cognito AdminCreateUser + RDS
PATCH	/admin/users/{user_id}	user admin 권한	RDS
DELETE	/admin/users/{user_id}	user admin 권한	Cognito AdminDeleteUser + RDS
GET	/auth/me	Cognito JWT	RDS principal
WS	/ws/factories/{factory_id}?token=<JWT>	공장 접근 권한	Redis Pub/Sub

---

Health와 Readiness

/healthz는 process liveness만 확인하고 항상 {"status":"ok"}를 반환한다. ALB target health check와 ECS container health check가 이 endpoint를 사용한다.

/readyz는 실제 의존성 probe다.

Dependency key	Probe
dynamodb	설정된 첫 factory ID 또는 factory-a에 대해 ddb.get_factory_latest()
redis	get_redis() 후 ping()을 REDIS_PUBSUB_OPERATION_TIMEOUT_SECONDS 안에 수행
rds_metadata	check_metadata_db(settings)

하나라도 실패하면 HTTP 503과 {"status":"degraded","dependencies":...}를 반환한다. 정상 기준은 세 값 모두 ok다.

---

Auth/RBAC

REST API는 Authorization: Bearer <Cognito JWT>를 사용한다. WebSocket은 브라우저가 임의 header를 넣기 어렵기 때문에 ?token=<JWT>로 전달한다.

RBAC 흐름:

Cognito JWT
  -> JWKS 검증
  -> sub 추출
  -> RDS app_user 조회
  -> user_factory_access 조회
  -> Principal 생성
  -> router별 require_* 함수 적용

super_admin과 org_admin은 모든 공장 접근 및 사용자 관리 권한을 가진다. factory_admin 등 공장 범위 사용자는 user_factory_access에 등록된 공장만 조회할 수 있다. can_view_system 또는 관리자 권한이 있으면 /cloud-infra와 factory_id=cloud-infra report를 볼 수 있다.

---

저장소 접근

DynamoDB

services/ddb.py가 AEGIS-DynamoDB-FactoryStatus를 읽는다.

Key	사용 endpoint
pk=FACTORY#{factory_id}, sk=LATEST	/factories, /factories/{factory_id}, /readyz
sk=HISTORY#STATE#{iso}	1시간 이하 history raw snapshot
sk=GRAPH#5M#{iso}	1시간 초과 chart aggregate
pk=CLOUD#infra, sk=LATEST	/cloud-infra
pk=CLOUD#infra, sk=HISTORY#FAST#... 또는 HISTORY#SLOW#...	/cloud-infra/history

Batch/list mode는 기본 DASHBOARD_FACTORY_DISCOVERY_MODE=batch_get이고 DASHBOARD_FACTORY_IDS=factory-a,factory-b,factory-c를 사용한다.

S3

services/s3.py는 aegis-bucket-data의 report와 image snapshot prefix를 읽는다.

reports/daily/yyyy=YYYY/mm=MM/dd=DD/{target}/report.md
image_snapshot/factory_id={factory_id}/yyyy=YYYY/mm=MM/dd=DD/hh=HH/{filename}

Report 목록은 ListObjectsV2, 본문은 GetObject로 읽는다. Image Snapshot 목록은 S3 partition을 제한해 ListObjectsV2로 조회하고, 브라우저가 직접 받을 수 있는 presigned GET URL을 반환한다. 실패/timeout은 504로 변환한다.

RDS PostgreSQL

RDS는 user/factory/RBAC metadata 저장소다. 주요 table은 factory, app_user, user_factory_access, audit_log다. Backend startup은 DATABASE_AUTO_CREATE_METADATA=true일 때 schema와 configured factory metadata를 idempotent하게 준비한다.

Redis

Redis는 TLS/AUTH가 켜진 ElastiCache Redis다. Backend는 WebSocket endpoint에서 factory:update:{factory_id} channel을 subscribe하고 메시지를 browser WebSocket으로 전달한다. Redis client는 explicit socket connect/read timeout과 health check interval을 설정한다.

---

Warmup, Timeout, Cache

Backend startup hook은 RDS metadata schema를 확인/생성하고 첫 factory의 DynamoDB latest를 읽어 DDB connection pool을 warmup한다. 목적은 cold start 직후 동시 요청이 모두 느린 첫 DDB 호출에 묶여 504로 확산되는 것을 줄이는 것이다.

주요 timeout/cache 값:

설정	값
DDB connect/read/operation	2s / 5s / 12s
DDB max attempts	2
DDB max pool connections	20
DDB max concurrent operations	10
S3 connect/read/operation	2s / 5s / 12s
S3 max attempts / pool	2 / 10
Redis connect/read/pubsub operation	2s / 5s / 6s
Cognito JWKS timeout / TTL	5s / 3600s
/factories process cache	10s

History endpoint는 since query를 지원해 delta refresh가 가능하다. 1시간 이하 window는 HISTORY#STATE#, 1시간 초과 window는 GRAPH#5M#를 사용한다.

---

ECS Auto Scaling

ecs_autoscaling.tf는 ECS service DesiredCount를 Application Auto Scaling target으로 등록한다.

정책	기준
Primary	ALBRequestCountPerTarget, 기본 target 40 req/target/min
Safety net	ECSServiceAverageCPUUtilization, 기본 target 50%
Cooldown	scale-out 60s, scale-in 300s
Capacity	demo 기준 desired/running 2, Application Auto Scaling min 2 / max 2

현재 demo profile은 warm task 2개를 유지하는 쪽에 무게를 둔다. Terraform은 ECS service의 desired_count와 task_definition 변경을 ignore하여 deployment/autoscaling과 충돌하지 않게 한다.

---

명시적 비범위

Dashboard Backend는 다음을 직접 호출하지 않는다.

• Hub EKS API
• ArgoCD API
• Spoke K3s API
• Tailscale 관리 API
• CloudWatch/EKS/Kubernetes live API를 통한 cloud infra 조회

Cloud infra 화면도 collector가 DynamoDB에 만든 read model을 읽는다. Dashboard는 준실시간 관제 read path이며 제어 plane API가 아니다.