Repository Structure

Các module trong repository bám theo client, integration, rendering service và cách thực thi renderer được trình bày trong kiến trúc. Bản đồ dưới đây giúp xác định điểm bắt đầu khi thay đổi một chức năng.

Bản đồ mã nguồn

Module, artifact và kiểm tra

Module	Trách nhiệm chính	Source	Artifact hoặc runtime	Kiểm tra
Playground	Soạn thảo, preview và export trong browser	server/src/main/resources/web/	Asset trong rendering image	Build server và browser smoke
VS Code Extension	Đọc editor, preview, export và giữ token	vscode-extension/	VSIX	npm --prefix vscode-extension test
GitLab MR Browser Extension	Đọc merge request, ghép stable ID và so sánh sơ đồ	browser-extension/	Manifest V3 package	npm --prefix browser-extension test
GitLab Markdown Integration	Xử lý fence trong document pipeline	deploy/gitlab-krokup/	Custom GitLab image	Ruby unit test và GitLab smoke
Confluence Forge App	Macro UI, resolver, page event, SVG cache và render policy	confluence-code-to-uml-poc/	Forge app, Forge KVS và Custom UI bundles	npm --prefix confluence-code-to-uml-poc test
Documentation Website	Build và phát hành tài liệu tĩnh	docs/, mkdocs.yml	Static site/	Strict build, navigation và link tests
Node.js Gateway	Public API, request policy, cache và observability	gateway/src/	Process trong rendering image	npm --prefix gateway test
Java Core	Options, renderer routing và output processing	server/src/main/java/	Java JAR trong rendering image	.\\mvnw.cmd -pl server test
Browser Companions	Render bằng Node.js và Chrome dùng chung	mermaid/, bpmn/, excalidraw/, diagrams.net/	Process trong rendering image	Module test và production smoke
Pydia Sidecar	Chạy Python qua Unix socket trong sandbox	pydia/	Pydia container image	python -m unittest discover -s pydia và gVisor verify
Deployment	Build image, Compose và cấu hình host	Dockerfiles, Compose files, deploy/, ops/	Runtime images và deployment manifests	Compose config và image smoke

Playground nằm trong server/ để được đóng gói cùng rendering image. Khi chạy, HTML và JavaScript của Playground vẫn hoạt động như một browser client gọi API của Gateway.

Client sản phẩm

Playground được phục vụ từ rendering runtime nhưng chạy như một browser client. VS Code Extension hoạt động trong Extension Host; GitLab MR Browser Extension chia logic giữa content script và service worker. Parser dùng diagram-id để ghép sơ đồ ổn định nhưng loại metadata này trước khi gửi mã tới Gateway. Khi request contract thay đổi, Gateway, OpenAPI và hướng dẫn của các client liên quan cần được cập nhật cùng nhau.

Các integration

GitLab Markdown Integration mở rộng document pipeline trong custom GitLab image. Confluence Forge App tách Custom UI trong browser khỏi Resolver và Page Event ở Forge backend. src/render-cache.js định nghĩa key, TTL và giới hạn SVG; adapter KVS nằm trong src/resolvers/index.js. Website tài liệu được MkDocs build và Wrangler phát hành lên Cloudflare. GitLab session, Forge credential và Gateway token được giữ tại thành phần thực sự sử dụng chúng; rendering service chỉ nhận request theo Gateway contract.

Rendering service

gateway/src/ là điểm tiếp nhận HTTP công khai viết bằng Node.js. Authentication, CORS, rate limit, cache, ETag, timeout, metrics và cách chuyển tiếp request được triển khai tại đây và đối chiếu với docs/api-docs.yaml.

server/src/main/java/ chứa Java Core, universal options, renderer registry và output processing. Các module renderer khác tại repository root cung cấp adapter và dependency dành cho từng engine.

Thực thi renderer

mermaid/, bpmn/, excalidraw/ và diagrams.net/ là browser companions dùng Chrome chung trong rendering image. Thay đổi browser lifecycle hoặc companion protocol cần được kiểm tra trên toàn bộ nhóm engine này.

pydia/ chứa Unix socket server và Python worker. Giao thức của Pydia còn liên quan tới Java adapter trong server/, Dockerfile.pydia, Compose volume và cấu hình gVisor tại deploy/gvisor/.

Build và phát hành

Dockerfile.render build Java JAR, cài Gateway và browser companions, sau đó ghép chúng với native renderer từ Kroki base image. Dockerfile.pydia tạo image cho sidecar. compose.vps.yml nối hai image bằng Unix socket volume và gán runsc-pydia cho Pydia container.

VSIX, Manifest V3 package, custom GitLab image, Forge app và static website có pipeline phát hành riêng. Các thư mục site/, target/, dist/ cùng file ZIP và VSIX là output được tạo lại từ source và cấu hình build.

Tìm mã nguồn theo thay đổi

• Endpoint, authentication, cache, CORS hoặc request limits: gateway/.
• Universal option, theme, renderer registration hoặc output processing: server/ và module renderer liên quan.
• Playground: server/src/main/resources/web/playground.html.
• VS Code preview hoặc export: vscode-extension/.
• Review merge request và stable diagram pairing trên GitLab: browser-extension/.
• Fence processing trong GitLab Markdown: deploy/gitlab-krokup/.
• Confluence macro, Resolver, Page Event hoặc SVG cache: confluence-code-to-uml-poc/.
• Pydia protocol hoặc sandbox: server/, pydia/, Dockerfile.pydia và deploy/gvisor/.
• Port, volume và deployment policy: Compose files, Dockerfiles và deploy/.
• API contract: docs/api-docs.yaml, tài liệu kiến trúc và hướng dẫn client.

Lệnh build/test và điều kiện hoàn tất thay đổi nằm trong Developer Guide; runbook triển khai nằm trong Operations.