Repository Structure¶

Repository chứa cả phần sản phẩm do nhóm phát triển, Gateway và rendering runtime kế thừa từ Kroki. Không phải mọi thư mục renderer ở root đều là một sản phẩm ngang hàng. Khi tìm mã nguồn, hãy bắt đầu từ trải nghiệm cần thay đổi rồi đi theo request tới Gateway và Java core khi cần.

1. Các nhóm mã nguồn¶

Kroki

Sơ đồ nhóm các thư mục theo ownership. Playground là ngoại lệ về vị trí vật lý: assets nằm trong server/ để được đóng gói vào JAR, nhưng chạy trong browser và gọi Gateway như một entry point sản phẩm. Documentation được tách thành nhóm nguồn riêng; website sinh từ documentation gọi Gateway khi browser tải diagram.

2. Cấu trúc chính¶

.
├── gateway/                         Node.js public HTTP entry
├── vscode-extension/                VS Code preview and export
├── browser-extension/               GitLab MR Before/After review
├── confluence-code-to-uml-poc/      Confluence Forge integration
├── deploy/gitlab-krokup/            GitLab document integration
├── server/
│   ├── src/main/java/               Java core and renderer adapters
│   └── src/main/resources/web/      Playground assets
├── mermaid/                         Browser companion
├── bpmn/                            Browser companion
├── excalidraw/                      Browser companion
├── diagrams.net/                    Browser companion
├── pydia/                           Isolated Python renderer server
├── deploy/                          Runtime entrypoint and deployment assets
├── ops/                             Operational support
├── scripts/                         Build and maintenance scripts
├── Dockerfile.render                Rendering image
├── Dockerfile.pydia                 Pydia sandbox image
├── compose.code-to-uml.yml          Local Compose profile
├── compose.vps.yml                  Production VPS profile
├── mkdocs.yml                       Documentation site configuration
├── requirements-docs.txt            Documentation build dependencies
└── docs/
    ├── Architecture/                System and software architecture
    ├── Using Code To UML/           Task-oriented user guides
    ├── Reference/                   API, operations and developer reference
    ├── project/                     Reviewed source material, excluded from website
    └── api-docs.yaml                OpenAPI contract

Các renderer module khác ở repository root chủ yếu thuộc nền tảng Kroki-derived. Chỉ cần mở chúng khi thay đổi engine tương ứng, build image hoặc kiểm tra tính tương thích của runtime.

3. Vị trí khi cần thay đổi¶

Khi cần thay đổi	Nơi bắt đầu
Gateway endpoint, xác thực, cache, CORS hoặc giới hạn	`gateway/`
Playground UI hoặc hành vi trong trình duyệt	`server/src/main/resources/web/`
VS Code command, preview hoặc nơi lưu token	`vscode-extension/`
GitLab MR review	`browser-extension/`
GitLab document rendering và fence params	`deploy/gitlab-krokup/`
Confluence event, resolver hoặc macro UI	`confluence-code-to-uml-poc/`
Universal params, theme, output processing hoặc renderer registration	`server/`
Mermaid, BPMN, Excalidraw hoặc diagrams.net browser rendering	Companion directory tương ứng và shared browser runtime
Pydia protocol hoặc sandbox execution	`server/`, `pydia/` và `Dockerfile.pydia`
Tài nguyên VPS, port, volume hoặc chính sách restart	`compose.vps.yml`, Dockerfiles và `deploy/`
HTTP API contract	`docs/api-docs.yaml`
Cấu trúc website và navigation	`mkdocs.yml` cùng ba nhóm tài liệu trong `docs/`
Giao diện website tài liệu	`docs/stylesheets/`, `docs/javascripts/` và `docs/assets/`

4. Từ mã nguồn đến artifact¶

Dockerfile.render build Java JAR từ server/, cài Gateway và browser companions, sau đó ghép chúng với native renderer từ base image Kroki. Build không phụ thuộc vào server/target có sẵn.

Dockerfile.pydia tạo image riêng cho source Python được gửi. Compose nối image này với rendering image bằng named volume chứa Unix socket; Pydia, Python worker và rendering token không nằm trong cùng một ranh giới bảo mật.

VS Code extension, custom image hỗ trợ GitLab documents, MR browser extension và Confluence Forge app không được đóng gói vào rendering image. Mỗi phần có quy trình build, test và phát hành riêng, dù đều gọi cùng Gateway.

Website MkDocs cũng là artifact độc lập. docs/ chứa Markdown, stylesheet, JavaScript và font nguồn; requirements-docs.txt khóa toolchain dùng để build. Thư mục site/ là output được tạo lại từ các nguồn này, không phải nơi chỉnh sửa website. mkdocs.yml chuyển diagram code block trong Markdown thành encoded image URL tại build time; website artifact không chứa Java core, Gateway hoặc rendering token.