Vault AMR Fulfillment Twin Architecture
이 문서는 현재 Next.js 데모 앱에 구현된 logistics digital twin의 구조를 설명한다. 이 twin은 로봇 제어 시스템이 아니라, synthetic source-world를 operationally legible하게 시각화하고, AI-ready data orchestration이 어떤 evidence를 기반으로 작동해야 하는지 보여주는 demonstration layer다.
1. Twin의 목적
이 앱의 digital twin은 단순 3D 창고 배경이 아니다. 목적은 source-world의 여러 시스템 신호를 물리 공간, 실행 상태, 병목, lineage, evidence chain으로 번역해 보이는 것이다. 즉, 화면의 주요 가치는 "예쁜 warehouse"가 아니라 "어떤 source evidence가 어떤 운영 판단으로 연결되는지"를 공간적으로 이해시키는 데 있다.
2. Technology stack
Application
Next.js 16.2.9, React 19.2.4, TypeScript 기반 single-page operational demo다.
3D rendering
three, @react-three/fiber, @react-three/drei를 사용해 React component로 scene graph를 구성한다.
Visual effects
@react-three/postprocessing의 bloom, vignette와 material lighting을 사용해 control-room quality를 만든다.
Main workspace: src/components/twin/TwinWorkspace.tsx
Main 3D scene: src/components/twin/TwinScene.tsx
Types: src/lib/twin/types.ts
Runtime fixture: src/data/generated/twin-scenario.json
3. Data contract
Twin은 raw CSV/JSONL을 runtime에서 직접 parse하지 않는다.
생성기가 source exports와 private replay를 만든 뒤, 앱용 fixture인 twin-scenario.json으로 컴파일한다.
이 방식은 UI를 빠르게 유지하면서도 source-world와 validation report의 출처를 분리한다.
| Fixture field | 역할 | 사용 위치 |
|---|---|---|
locations, layout_edges |
facility geometry, route network, blocked edge, zone labels의 기반이다. | Location blocks, route network, camera target, task corridors |
assets, event_positions |
AMR, charger, station 위치와 timeline별 robot movement를 만든다. | Robots, robot trails, charging stations |
timeline_events |
사용자가 클릭하는 replay timeline의 primary state다. | Left rail, incident inspector, camera preset, focus beacon |
wcs_tasks, shipments, handling_units |
작업 corridor, dock/truck state, cargo field를 구성한다. | Task corridors, dock doors, cargo field, outbound yard |
labor_shift_roster |
shift별 labor coverage, certification, break coverage gap, approval lane capacity를 표시한다. | Source tabs, selected source record anchor, labor-driven evidence cards |
resource_capacity, capacity_stress_by_event |
운영 병목을 3D heat layer와 right-rail capacity panel에 표시한다. | Resource capacity layer, capacity stress panel |
source_sync_runs |
event별 connector freshness, lag, retry, rejected row, partial/stale source window를 표시한다. | Source freshness panel, sync-run source table, evidence chain freshness |
source_event_ledger |
원천 row를 source file, source record id, scenario event, entity/location refs, freshness window, replay order로 묶는다. | Event ledger source tab, selected source record anchor, future incremental replay mode |
handling_unit_lineage |
carton/tote movement path와 dirty movement state를 표시한다. | Handling-unit lineage layer, lineage panel |
decision_trace, evidence_chains, causal_replay |
source evidence, decision pressure, causal transition을 사람이 읽는 layer로 만든다. | Evidence overlay, decision trace panel, causal replay panel |
4. Workspace layout
UI는 persistent 3D scene을 중심에 두고, 좌측에는 scenario controls와 source report links, 우측에는 selected event의 incident inspector를 둔다. 물류 demo는 반복 탐색이 핵심이므로 landing page나 marketing copy 대신 control-room 형태의 작업 화면을 첫 화면으로 둔다.
Left rail
scenario summary, validation status, source report links, timeline event buttons를 제공한다.
Scene stage
facility, racks, AMR, route, task, dock, capacity, lineage, evidence를 3D로 렌더링한다.
Right rail
selected event의 metric, lineage, capacity, causal replay, evidence chain, decision trace, intervention options를 보여준다.
5. 3D scene layers
3D scene은 하나의 거대한 mesh가 아니라 운영 의미별 layer로 쪼개져 있다. 이렇게 나누면 source-world가 확장될 때 특정 layer만 개선할 수 있고, ontology layer가 붙더라도 시각 표현을 안정적으로 유지할 수 있다.
| Layer | 역할 | 구현 의도 |
|---|---|---|
WarehouseEnvelope, FloorMarkings, OverheadInfrastructure |
창고 외곽, 바닥 동선, 조명/기둥/상부 구조 | 2D diagram 느낌을 줄이고 실제 warehouse volume을 만든다. |
LocationBlocks, ZoneLabels |
zone별 location block과 labels | source location을 물리 좌표로 anchoring한다. |
StorageRacks, CargoField |
reserve/pick rack, carton/tote/pallet visual | fulfillment center density를 보여주고 handling unit의 물리성을 만든다. |
ConveyorAndPackLine, SafetyAndWorkcellDetails |
pack line, workcell, safety zone | pack/stage bottleneck이 실제 작업 공간에 존재함을 보여준다. |
DockDoorsAndTrucks, ExteriorDockYard |
dock door, truck, yard, appointment state | TMS carrier arrival variance와 dock slack compression을 눈에 보이게 만든다. |
ChargingStations, Robots, RobotMotionTrails |
charger, AMR, robot trail | AMR-17 stale availability와 forced charge를 공간적으로 보여준다. |
RouteNetwork, TaskCorridors, FlowArcs |
layout edge, active task path, flow pressure | WCS task와 physical route blockage를 연결한다. |
OperationalHeatLayer, ResourceCapacityLayer |
severity heat, capacity bottleneck markers | constraint가 발생한 source-world location을 즉시 파악하게 한다. |
SourceFreshness3DLayer |
event별 source sync lag, stale/partial/watch/current freshness beacon | backend connector 상태를 3D 운영 공간에 배치해 어떤 source가 판단을 지연시키는지 보이게 한다. |
SelectedSourceRecordLayer |
사용자가 inspect한 source row의 deterministic physical anchor | 테이블 row와 warehouse location을 직접 연결해 source data가 twin 위에서 어디에 붙는지 검증하게 한다. |
HandlingUnitLineageLayer |
unit movement path와 dirty state marker | late, missing, blocked, inferred lineage가 어디에서 발생했는지 보여준다. |
SourceEvidenceOverlayLayer, SceneCallouts, FocusBeacon |
source evidence card, callout, selected event focus | 3D 화면이 단순 visual이 아니라 explainability surface가 되게 한다. |
6. Source data to visual mapping
twin의 핵심은 각 source signal을 적절한 physical anchor에 매핑하는 것이다. 같은 incident라도 WMS, AMR, TMS, capacity, lineage는 서로 다른 관찰 지점을 가진다.
| Source | Visual anchor | 표현 방식 |
|---|---|---|
| WMS orders and inventory | pick face, reserve, affected order list | right rail metric, source samples, inventory shortage narrative |
| WCS tasks | task source/destination locations | task corridor line, active work pressure, blocked route signal |
| AMR snapshots and events | selected robot, charger, route trail | robot body, battery/charge state, motion trail, AMR evidence card |
| TMS shipments | Dock 3, outbound yard, truck | truck state, dock marker, dock slack metric, TMS evidence card |
| Scan events | pack, stage, dock, cold zone locations | lineage marker, missing/late scan state, source evidence card |
| Capacity snapshots | top bottleneck resource location | capacity stress marker, utilization label, capacity panel |
| Labor shift roster | role home location or linked constrained resource | labor roster source tab, selected row anchor, staffing constraint evidence |
| Source sync runs | selected event and affected source export | right-rail freshness panel, max lag, degraded source count, rejected row count, sync-run source tab |
| Source event ledger | ledger row primary location or source-derived entity location | event ledger source tab, source record id, replay order, selected row anchor |
| Exception events | focus location or operations context | incident callout, intervention options, causal replay panel |
7. Source evidence overlay
최신 twin layer는 decision_trace.signals를 읽어 source evidence card를 3D 공간에 배치한다.
이 layer의 의도는 "오른쪽 패널에 근거가 있다"가 아니라, 근거 자체가 warehouse의 어느 위치와 연결되는지 시각적으로 보여주는 것이다.
source system별 physical anchor는 다음처럼 잡는다.
TMS와 dock signal은 DOCK-03, AMR signal은 selected robot 또는 CHG-01, labor signal은 role의 home location 또는 constrained resource location, capacity signal은 top bottleneck location, lineage signal은 non-confirmed movement location, WCS/task signal은 active task source/destination, scan signal은 stage/cold/pack 위치에 연결된다.
8. Event-aware camera
사용자가 timeline event를 선택하면 camera preset이 selected event의 operational focus로 이동한다. 단순 orbit camera만 제공하면 CTO나 고객이 어디를 봐야 하는지 매번 찾아야 하므로, event semantics가 camera target을 결정하게 했다.
| Condition | Camera focus | Reason |
|---|---|---|
T00 |
full facility overview | baseline에서는 전체 source-world 구조를 먼저 보여준다. |
focus location includes DOCK or dock slack is below threshold |
dock and staging view | carrier early arrival과 dock cutoff compression을 빠르게 보여준다. |
affected assets include AMR-17 or focus is charger |
AMR and charging view | stale availability와 forced charge 문제를 robot 위치에서 설명한다. |
focus location includes COLD or CHOKE |
cold-zone bottleneck view | physical aisle blockage가 WCS/AMR 작업 흐름에 주는 영향을 보여준다. |
focus location includes PACK or STAGE |
pack and staging view | partial recovery와 handling-unit lineage 상태를 한 화면에 둔다. |
9. Visual design choices
데모의 visual direction은 operational control room이다. 물류/항만 같은 conservative environment에서는 장식적인 hero보다, 빠르게 스캔되고 근거가 보이는 dense interface가 더 설득력 있다.
- dark background를 사용해 3D scene, source evidence card, severity color가 명확하게 드러나게 했다.
- zone color는 location type을 구분하는 데만 사용하고, critical state는 red/amber/green severity scale로 분리했다.
- warehouse envelope, rack, dock yard, charger, conveyor, cargo를 추가해 단순 2D map이 아니라 실제 facility volume처럼 보이게 했다.
- 텍스트 설명보다 source card, utilization label, lineage marker처럼 근거가 붙은 visual element를 우선했다.
- right rail은 decision context를 읽는 공간이고, scene은 physical causality를 보는 공간으로 분리했다.
10. Verification approach
이 twin은 data generation과 UI rendering을 분리해서 검증한다. 데이터가 맞는지와 화면이 보이는지는 서로 다른 실패 모드이므로, 각각 따로 확인해야 한다.
| Check | Command or method | Pass condition |
|---|---|---|
| Data generation | npm run generate:data |
source exports, private truth, reports, app fixture가 같은 scenario id로 생성된다. |
| Data validation | npm run validate:data |
required files, referential integrity, count budgets, source-event ledger replayability, labor roster constraints, capacity math, lineage dirty states, replay metadata가 통과한다. |
| Application build | npm run build |
Next.js app이 TypeScript/React build를 통과한다. |
| Canvas visual QA | Playwright screenshot and canvas-pixel inspection | desktop/mobile viewport에서 canvas가 nonblank이고, scene이 프레임 안에 있으며, 주요 panel text가 겹치지 않는다. |
11. Next upgrades
다음 단계는 시각적 화려함을 더하는 것보다, source-world의 복잡도가 올라가도 twin이 operational evidence를 잃지 않게 만드는 것이다. 그래야 ontology compiler와 agent layer가 붙었을 때 demo가 단순 animation이 아니라 AI-ready infrastructure proof가 된다.
- source event replay를 시간축 animation으로 강화해 JSONL stream ingestion 느낌을 만든다.
- AMR task queue와 blocked route를 더 세밀한 pathfinding visual로 표시한다.
- dock appointment, staging lane occupancy, carrier SLA risk를 별도 mini-map layer로 만든다.
- ontology compiler가 생성한 node/edge를 source-world 위에 overlay하는 semantic graph mode를 추가한다.
- 실제 Vault sample data가 들어오면 synthetic id와 real source id의 mapping/coverage report를 만든다.
- scenario editor를 추가해 carrier arrival, AMR failure, labor shortage 같은 what-if parameter를 조정할 수 있게 한다.