Zapee Automation Engine — Architecture

flowchart LR
  subgraph KNOWLEDGE["Kiến thức từng nền tảng"]
    DB["Recipe active trong
PostgreSQL"]
    BHX["bhx.json
Đã có"]
    COOP["coop.json
Mục tiêu"]
    WAL["walmart.json
Mục tiêu"]
    CK["circlek.json
Mục tiêu"]
  end

  subgraph SERVER["Agent Server"]
    WS["WebSocket Session"]
    RES["Recipe Resolver"]
    ENGINE["Core Automation Engine
dùng chung"]
    LEGACY["Legacy Playbook /
Controller"]
  end

  subgraph BROWSER["Một Playwright Page duy nhất"]
    ACTION["Click / Fill / Navigate / Wait"]
    PAGE["Trang nhà bán thật"]
    CDP["CDP Screencast"]
  end

  subgraph ZAPEE["Zapee Web / CBS"]
    CART["Giỏ hàng Zapee"]
    INPUT["Input đơn hàng theo phiên"]
    USER["Người dùng thao tác"]
    SCREEN["Màn hình stream"]
  end

  DB -->|"Ưu tiên"| RES
  BHX -->|"Fallback file"| RES
  COOP -.-> RES
  WAL -.-> RES
  CK -.-> RES

  RES -->|"Có recipe và chain được bật"| ENGINE
  RES -->|"Chưa có recipe"| LEGACY
  ENGINE --> ACTION
  LEGACY --> ACTION
  ACTION --> PAGE
  PAGE --> CDP
  CDP --> WS

  CART --> INPUT
  INPUT --> WS
  WS --> RES
  WS --> SCREEN
  USER --> SCREEN
  SCREEN -->|"Click / gõ / scroll"| WS
  WS --> PAGE

  click DB showDetail "Deployment active trong PostgreSQL được ưu tiên cho production."
  click BHX showDetail "BHX là pilot đã có recipe JSON chạy bằng Automation Engine."
  click COOP showDetail "Mục tiêu chuyển dần logic Co.op sang coop.json dùng cùng schema."
  click WAL showDetail "Walmart hiện vẫn còn nhiều playbook riêng; walmart.json chưa có."
  click CK showDetail "Circle K có thể dùng chung Engine sau khi có recipe đã review."
  click RES showDetail "Resolver chọn recipe theo chain và environment: DB trước, file fallback sau."
  click ENGINE showDetail "Engine chỉ đọc checkpoint, condition, locator, action và retry; không chứa logic riêng của shop."
  click LEGACY showDetail "Khi chưa có recipe, server tiếp tục dùng playbook/controller hiện tại."
  click WS showDetail "WebSocket mang run_order, status, screencast và remote input trong cùng session."
  click PAGE showDetail "Automation, training, stream và human takeover đều bám đúng một Playwright page."
  click CDP showDetail "CDP gửi frame JPEG của page về frontend để người dùng quan sát."
  click INPUT showDetail "Dữ liệu người mua và đơn hàng chỉ nằm trong session, không ghi cứng vào recipe."
  click SCREEN showDetail "Canvas hiển thị frame và gửi ngược click, bàn phím, scroll về browser."
          

flowchart LR
  subgraph OPS["Ops / QC"]
    SELECT["1. Chọn chain, sản phẩm,
worker và artifact"]
    REVIEW["8. Review / Reject"]
    ACTIVATE["9. Activate version
theo environment"]
  end

  subgraph SESSION["Training Session"]
    TOKEN["2. Signed training token"]
    OPEN["3. Mở Playwright page
đang screencast"]
    OBSERVE["4. Codex / Claude
observe_page"]
    PROPOSE["5. propose_action"]
    GATEWAY["6. Action Gateway
kiểm tra và thực thi"]
    HUMAN{"Gặp OTP / CAPTCHA /
login / review?"}
    TAKEOVER["Human takeover
và resume"]
    COMPLETE["7. complete
automationRecipe JSON"]
  end

  subgraph DATABASE["PostgreSQL"]
    VALIDATE["Validate schema,
chain và allowedHosts"]
    CANDIDATE["Recipe version
candidate"]
    DEPLOY["Deployment active"]
  end

  SELECT --> TOKEN --> OPEN --> OBSERVE --> PROPOSE --> GATEWAY
  GATEWAY --> HUMAN
  HUMAN -->|"Không"| OBSERVE
  HUMAN -->|"Có"| TAKEOVER --> OBSERVE
  OBSERVE -->|"Tới ready_for_user_place_order"| COMPLETE
  COMPLETE --> VALIDATE --> CANDIDATE
  CANDIDATE --> REVIEW --> ACTIVATE --> DEPLOY

  click SELECT showDetail "Operator chọn dữ liệu training trong /ops/training."
  click TOKEN showDetail "Token có chữ ký khóa đúng controller và artifact được phép."
  click OPEN showDetail "Training mở website thật trên cùng page đang stream."
  click OBSERVE showDetail "AI đọc URL và DOM đã lọc qua zapee_browser MCP."
  click PROPOSE showDetail "Mỗi lượt AI chỉ đề xuất một action để dễ kiểm soát."
  click GATEWAY showDetail "Gateway kiểm tra action trước khi click, fill, navigate hoặc wait."
  click HUMAN showDetail "Bước nhạy cảm luôn có thể dừng để operator thao tác trực tiếp."
  click TAKEOVER showDetail "Operator xử lý trên stream rồi resume, không mở browser khác."
  click COMPLETE showDetail "AI trả về automationRecipe JSON khi đã tới ranh giới review."
  click VALIDATE showDetail "Agent-server kiểm tra schema, canonical chain và hostname."
  click CANDIDATE showDetail "Recipe được lưu thành version candidate bất biến, không tự ghi đè file local."
  click REVIEW showDetail "Operator xem JSON và quyết định review hoặc reject."
  click ACTIVATE showDetail "Chỉ version reviewed mới được activate cho môi trường."
          

flowchart LR
  subgraph CLIENT["Zapee / CBS"]
    START["1. Người dùng bấm
Tiếp tục đặt hàng"]
    PAYLOAD["2. run_order
dữ liệu theo session"]
    STATUS["Status / checkpoint /
event về UI"]
    MANUAL["Người dùng takeover
trên stream"]
  end

  subgraph SERVER["Agent Server"]
    RESOLVE["3. Resolve recipe
chain + environment"]
    PIN["4. Pin recipe version
cho cả session"]
    DETECT["5. Detect URL / DOM
chọn checkpoint"]
    ACTION["6. Chạy action"]
    COMPLETE{"Checkpoint
complete?"}
    PAUSE{"Cần người dùng?"}
    RESUME["Detect lại và resume
từ checkpoint phù hợp"]
    READY["7. checkout_ready
boundary review"]
  end

  subgraph SHOP["Website nhà bán"]
    PAGE["Playwright Page"]
    REVIEW["Trang review đơn"]
    FINAL["Xác nhận cuối
do người dùng quyết định"]
  end

  START --> PAYLOAD --> RESOLVE --> PIN --> DETECT --> ACTION --> PAGE
  PAGE --> COMPLETE
  COMPLETE -->|"Chưa"| ACTION
  COMPLETE -->|"Xong"| PAUSE
  PAUSE -->|"Còn checkpoint"| DETECT
  PAUSE -->|"OTP / CAPTCHA / manual"| STATUS --> MANUAL --> PAGE
  MANUAL --> RESUME --> DETECT
  PAUSE -->|"Đã chuẩn bị checkout"| READY --> REVIEW --> FINAL
  ACTION --> STATUS

  click START showDetail "Đơn bắt đầu khi người dùng xác nhận tiếp tục từ Zapee/CBS."
  click PAYLOAD showDetail "Tên, điện thoại, địa chỉ, sản phẩm, slot và payment đi theo run_order."
  click RESOLVE showDetail "Server lấy recipe active từ DB, nếu chưa có thì dùng file fallback."
  click PIN showDetail "Version được giữ cố định trong suốt session đang chạy."
  click DETECT showDetail "Engine đọc URL/DOM để biết đang ở checkpoint nào."
  click ACTION showDetail "Action deterministic gồm navigate, click, fill, check, press, wait, foreach, branch và send_event."
  click COMPLETE showDetail "Engine chỉ đi tiếp khi điều kiện complete của checkpoint đã thỏa."
  click PAUSE showDetail "Auto có thể pause; manual guide chỉ hướng dẫn và không tự click/fill."
  click MANUAL showDetail "Người dùng thao tác trực tiếp trên đúng page qua stream."
  click RESUME showDetail "Resume không chạy lại từ đầu và không replay action/item đã hoàn tất."
  click READY showDetail "Engine kết thúc tại checkout_ready hoặc boundary review."
  click FINAL showDetail "Engine không được tự bấm nút xác nhận đặt hàng cuối."
          

flowchart LR
  subgraph BROWSER["Agent Server / Browser"]
    PAGE["Playwright Page"]
    CDP["Page.startScreencast"]
    FRAME["JPEG frame + URL +
viewport metadata"]
    DISPATCH["Dispatch remote input
vào Playwright"]
    ENGINE["Automation Engine"]
  end

  subgraph SOCKET["WebSocket Session"]
    OUT["screencast / status / event"]
    IN["remote_click / remote_key /
insert_text / remote_scroll"]
  end

  subgraph CLIENT["Zapee Frontend"]
    CANVAS["Canvas stream"]
    COORD["Quy đổi tọa độ
canvas → browser"]
    USER["Người dùng"]
    BOTLINE["Botline / timeline /
checkpoint UI"]
  end

  PAGE --> CDP --> FRAME --> OUT --> CANVAS
  ENGINE --> PAGE
  ENGINE --> OUT
  OUT --> BOTLINE

  USER -->|"Quan sát"| CANVAS
  USER -->|"Click / gõ / scroll"| COORD --> IN --> DISPATCH --> PAGE
  PAGE -->|"Frame mới"| CDP

  click PAGE showDetail "Trang nhà bán thật; mọi automation và input người dùng đều tác động lên page này."
  click CDP showDetail "Chrome DevTools Protocol chụp các frame JPEG liên tục."
  click FRAME showDetail "Server gửi đúng kích thước frame, URL và metadata cần thiết."
  click OUT showDetail "Kênh đi xuống mang hình ảnh, trạng thái Engine và event nghiệp vụ."
  click CANVAS showDetail "Frontend vẽ frame lên canvas để người dùng theo dõi."
  click BOTLINE showDetail "Status và checkpoint được hiển thị thành hướng dẫn trong UI."
  click USER showDetail "Người dùng có thể takeover khi cần xác minh hoặc chọn thủ công."
  click COORD showDetail "Tọa độ trên canvas được quy đổi về viewport thật của browser."
  click IN showDetail "Kênh đi lên mang click, phím, text và scroll."
  click DISPATCH showDetail "Agent-server gọi Playwright mouse/keyboard trên page đang active."
  click ENGINE showDetail "Engine và người dùng dùng chung page, không có browser thứ hai."