Container Architecture¶
1. Các container và quan hệ chính¶
Browser extension đọc dữ liệu từ GitLab nhưng tự gửi POST tới Gateway; Confluence Custom UI gọi Forge resolver và chỉ resolver gửi POST. Static website và GitLab document tạo image URL để browser gửi encoded GET. Nét liền biểu thị authenticated POST hoặc kết nối nội bộ; nét đứt biểu thị public encoded GET.
2. Lớp trải nghiệm sản phẩm¶
| Trải nghiệm | Container gửi request | Trách nhiệm |
|---|---|---|
| Playground | Playground trên browser | Soạn source, điều chỉnh params, xem trước và tải kết quả |
| VS Code extension | Extension host | Nhận dạng file/fence, Preview và xuất sơ đồ |
| GitLab document integration | Browser đọc tài liệu GitLab | Nhúng encoded image URL; self-managed GitLab có thể xử lý fence params trong Markdown pipeline |
| GitLab MR browser extension | Content script và service worker | Đọc thay đổi Markdown; hiển thị preview tài liệu và render Before/After theo yêu cầu |
| Confluence Forge app | Forge resolver | Macro editor lưu cấu hình; page event chuyển code block thành macro; resolver giữ token và gọi Gateway ở backend. |
| Static documentation | Browser đọc website | Tải SVG qua encoded URL được tạo lúc build tài liệu |
3. Gateway và Java core¶
Node.js Gateway là điểm vào HTTP công khai. Gateway xử lý xác thực cho POST, rate limit, CORS, giới hạn request/response, timeout, cache kết quả và ETag trước khi chuyển request vào Java core.
Java core giải mã source, xử lý và hợp nhất params, chọn renderer adapter và hoàn thiện kết quả. Engine đã được xác định từ endpoint hoặc ứng dụng gọi; core ánh xạ engine đó tới cách thực thi tương ứng, không thử lần lượt nhiều renderer để tìm kết quả.
4. Cách thực thi renderer¶
Java core có ba cách thực thi renderer:
| Cách thực thi | Thành phần |
|---|---|
| Embedded hoặc native | Thư viện JVM hoặc command có trong rendering image |
| Browser companion | Mermaid, BPMN, Excalidraw và diagrams.net dùng chung Google Chrome |
| Isolated sidecar | Pydia nhận request qua Unix socket và chạy trong sandbox không có IP network |
5. Dữ liệu và trạng thái¶
Rendering service không có database lưu sơ đồ. Cache kết quả, rate limit bucket và request đang xử lý nằm trong RAM của từng Gateway process, nên sẽ mất khi process restart. Source lâu dài vẫn nằm trong file, repository hoặc Confluence page; token nằm trong vùng lưu trữ tin cậy của ứng dụng hoặc tích hợp backend.
6. Ranh giới thay đổi giữa các ứng dụng¶
Gateway và Java core là hai tiến trình có trách nhiệm riêng nhưng cùng tạo nên rendering service. VS Code extension, GitLab document integration, MR browser extension, Confluence Forge app và website là các ứng dụng hoặc artifact tích hợp độc lập. Vì vậy thay đổi hostname, permission hoặc API contract có thể tác động tới nhiều ứng dụng dù logic renderer không đổi.