Structurizr: Vẽ kiến trúc phần mềm bằng code, không phải bằng tay

Nếu bạn đã từng phải maintain một đống diagram Confluence hay draw.io mà cứ vài tháng lại outdated một lần bạn biết cái cảm giác đó khó chịu thế nào. Dev thì đang code feature mới, còn diagram kiến trúc vẫn đang mô tả hệ thống từ hồi năm ngoái. Ai cũng biết nó sai, nhưng không ai có thời gian ngồi update.

Đây chính xác là vấn đề mà Structurizr sinh ra để giải quyết.

C4 Model và tại sao nó fit với cách dev nghĩ

Trước khi nói về Structurizr, cần hiểu một chút về C4 model vì Structurizr được build xung quanh nó hoàn toàn.

C4 model (do Simon Brown tạo ra, cũng chính là người tạo ra Structurizr) là một cách tiếp cận để mô tả kiến trúc phần mềm theo 4 tầng:

Cái hay của C4 là nó giống như zoom in/zoom out. Stakeholder cấp cao chỉ cần xem Level 1, tech lead cần Level 2-3, còn dev thì đào sâu vào Level 3-4. Mỗi audience có diagram phù hợp, không phải nhồi hết vào một cái diagram khổng lồ khó đọc.

Theo kinh nghiệm của mình, C4 model giải quyết được một vấn đề rất thực tế: dev và business thường dùng diagram khác nhau, nói chuyện với nhau mà không ai hiểu ai. C4 tạo ra một ngôn ngữ chung có hierarchy rõ ràng.

Structurizr DSL Khi diagram trở thành code

Đây mới là phần thú vị. Thay vì kéo thả, bạn viết Structurizr DSL một ngôn ngữ đặc thù (domain-specific language) để định nghĩa model kiến trúc. Từ một model đó, tool sẽ tự render ra tất cả các diagram bạn cần.

Một ví dụ đơn giản trông như thế này:

1workspace {
2
3    model {
4        user = person "Người dùng" "Sử dụng ứng dụng qua browser"
5
6        softwareSystem "E-commerce Platform" {
7            webApp = container "Web Application" "React SPA" "JavaScript/React"
8            api = container "API Server" "REST API" "Node.js/Express"
9            db = container "Database" "Lưu trữ dữ liệu" "PostgreSQL"
10            cache = container "Cache" "Session và product cache" "Redis"
11        }
12
13        user -> webApp "Truy cập qua HTTPS"
14        webApp -> api "Gọi API"
15        api -> db "Đọc/ghi dữ liệu"
16        api -> cache "Cache lookup"
17    }
18
19    views {
20        systemContext softwareSystem "SystemContext" {
21            include *
22            autoLayout
23        }
24
25        container softwareSystem "Containers" {
26            include *
27            autoLayout
28        }
29    }
30}

Bạn define model một lần, rồi declare các views khác nhau mỗi view là một diagram. Structurizr sẽ render tất cả từ cùng một source of truth đó.

Mình thấy cái này hay ở chỗ: relationship giữa các element chỉ cần define một lần. Khi bạn thêm một service mới vào model, tất cả các diagram liên quan đều tự động reflect sự thay đổi đó. Không có chuyện một diagram biết còn diagram kia không.

Architecture bên trong của project

Nhìn vào repo, Structurizr được tổ chức thành nhiều module riêng biệt, mỗi module có responsibility rõ ràng:

Cái structurizr-component là một feature mình thấy khá độc đáo. Nó có thể scan Java source code của bạn và tự động discover các component dựa trên annotation hoặc naming convention, rồi tích hợp vào model. Nghĩa là diagram Level 3 của bạn có thể được generate một phần từ chính code, giảm thiểu việc phải maintain thủ công.

structurizr-mcp thì mới hơn đây là MCP (Model Context Protocol) server, cho phép AI assistant như Claude hay Copilot có thể đọc và làm việc với architecture model của bạn. Đây là hướng đi khá thú vị khi AI ngày càng được dùng trong software development workflow.

Models as Code thực sự có nghĩa gì

Khái niệm "models as code" không chỉ là marketing tagline. Khi diagram của bạn là code:

Version control được: File DSL commit vào Git cùng với code. Bạn biết diagram thay đổi khi nào, ai thay đổi, tại sao thay đổi qua commit history. Pull request cho architecture change cũng có thể được review như code.

Diff được: Khi có thay đổi kiến trúc, bạn có thể git diff để thấy chính xác cái gì thay đổi. Không phải nhìn vào hai cái screenshot diagram rồi đoán.

CI/CD được: Bạn có thể integrate việc generate diagram vào pipeline. Mỗi khi merge vào main, diagram tự động được update và publish. Documentation không bao giờ stale.

Reuse được: Cùng một model, export ra nhiều format khác nhau tùy audience. Stakeholder thích PlantUML? Có. Team dùng Mermaid trong GitHub? Có. Muốn interactive diagram? Có luôn.

Anh em lưu ý điểm này: structurizr-export support rất nhiều output format, có nghĩa là bạn không bị lock-in vào Structurizr viewer. Model của bạn là portable.

Cách bắt đầu nhanh nhất

Có hai con đường:

Option 1 Thử ngay không cần cài gì: Vào playground.structurizr.com, paste DSL vào, xem kết quả ngay. Cực kỳ tiện để experiment.

Option 2 Chạy local với Docker:

1docker pull structurizr/lite
2docker run -it --rm -p 8080:8080 \
3  -v /path/to/your/workspace:/usr/local/structurizr \
4  structurizr/lite

Sau đó tạo file workspace.dsl trong folder đó, truy cập localhost:8080 là xong. Hot reload luôn save file là diagram update ngay.

Mình hay dùng option này khi làm việc với team. Commit file .dsl vào repo, ai cũng có thể chạy local và xem diagram mà không cần account hay service nào cả.

So sánh với các tool khác trên thị trường

So với PlantUML hay Mermaid những tool mà dev Việt Nam dùng khá nhiều Structurizr có một điểm khác biệt cơ bản: bạn define model, không phải define diagram. Với PlantUML, mỗi diagram là một file riêng, relationship phải viết lại ở mỗi diagram. Với Structurizr, relationship define một lần trong model, tất cả diagram đều dùng chung.

Tradeoff là learning curve của Structurizr DSL cao hơn một chút, và nó opinionated hơn bạn phải follow C4 model. Nếu bạn cần diagram tự do không theo chuẩn nào, PlantUML hay Mermaid sẽ flexible hơn.

Annotation-driven architecture documentation

Một feature mình thấy underrated là structurizr-annotation. Nếu bạn đang làm Java, bạn có thể annotate class trực tiếp:

1@Component
2@Description("Xử lý authentication và authorization")
3@Technology("Spring Security")
4public class AuthService {
5    // ...
6}

Rồi dùng structurizr-component scanner để tự động pull những thông tin này vào model. Diagram Level 3 của bạn sẽ reflect đúng codebase hiện tại, không phải cái gì đó ai đó vẽ tay từ 6 tháng trước.

Đây là hướng tiếp cận "documentation lives close to code" tương tự như cách JavaDoc hay OpenAPI annotation hoạt động, nhưng cho architecture diagram.

Khi nào nên dùng, khi nào không

Structurizr fit nhất với team/project:

• Có kiến trúc phức tạp cần document cho nhiều audience khác nhau
• Coi trọng documentation as code và muốn diagram trong version control
• Đang dùng hoặc muốn adopt C4 model
• Team size đủ lớn để việc maintain diagram thủ công trở thành pain point

Nếu bạn chỉ cần vẽ một cái diagram nhanh để present rồi quên đi, hay team chỉ 2-3 người và diagram không cần maintain lâu dài thì overhead của Structurizr có thể không worth it. Mermaid trong GitHub README lúc đó đơn giản và đủ dùng hơn.

Nhưng nếu bạn đang build một hệ thống mà sẽ tồn tại và evolve trong nhiều năm, với nhiều team cùng làm việc, cần onboard người mới thường xuyên thì investment vào Structurizr sẽ pay off rất nhanh. Diagram không bao giờ outdated, vì nó được maintain cùng với code.

Theo kinh nghiệm của mình, cái đau nhất không phải là vẽ diagram lần đầu mà là maintain nó sau 6 tháng khi hệ thống đã thay đổi nhiều. Structurizr giải quyết đúng cái pain point đó.