From Business Boxes to Microservices: A Technical Leader’s Guide to Application Architecture Diagrams

1. Essence of Application Architecture

Application architecture is the technical implementation of a business architecture; it shows how collaborative components realize business capabilities. Like literary translation, it must be faithful (no missing functions), expressive (accurate technical expression, e.g., async messaging), and elegant (avoid coupling payment core with marketing code).

2. The Art of Mapping: Four‑Step Translation

Step 1 – Identify Bounded Contexts : Recognise logical business boundaries such as Payment Core, Account, Payment Channel, and Marketing. A context may contain multiple services, but a service should not span multiple contexts.

Step 2 – Define Service Granularity : Choose a split dimension.

By business capability (recommended): e.g., split Payment Core into Payment Core Service, Payment Query Service.

By technical characteristic (cautious): e.g., extract a Risk‑Check Service, which may introduce distributed transactions.

By CQRS (read/write separation): separate write‑side (order, deduction) from read‑side (bill query, aggregation).

Golden rule: if two services must be updated together for a single business function, the split is too fine‑grained. Step 3 – Establish Service Contracts : Diagram lines are not decorative arrows; they represent strict API contracts. API names should reflect business intent, e.g., submitPaymentIntent instead of createOrder , and fetchInvitedUsersWithRewards instead of getUserList . Step 4 – Handle Cross‑Cutting Concerns : Platform services such as authentication, risk control, and configuration should be drawn as supporting layers and accessed via AOP or a service mesh, never by direct calls from business services.

3. Diagram Notation Standards

Service Box Shapes : rectangles for core domain services, cylinders for data stores, clouds for external dependencies. Color Semantics : green – stable core services; blue – supporting services; yellow – experimental services; red – legacy services. Dependency Line Semantics : Solid arrow – synchronous call with timeout. Dashed arrow – asynchronous message with topic name. Double‑arrow – warning of potential circular dependency. Dashed box with label – distributed transaction (e.g., payment + coupon joint settlement). If lines become too many, highlight only the core chain. 4. Two Presentation Forms Focused Form : shows only core services and their immediate upstream/downstream, suitable for project reviews. Panoramic Form : includes every in‑service, grouped by business domain with dashed boxes, and uses bold arrows for inter‑domain data flow, ideal for quarterly architecture reviews. 5. Two Levels of Architecture Diagrams Global View : abstract sub‑domains, each represented by 1‑3 core services; no databases, no detailed interfaces; uses dashed boxes to mark domain boundaries. Sub‑Domain Detail : expands a single domain to show all services, their call patterns (sync/async), timeout policies, external dependencies at the edge, and colour‑coded cross‑cutting concerns. 6. Typical Practical Scenarios Scenario 1 – Existing System Landscape : When taking over an old system, first produce a realistic current‑state diagram (do not start refactoring). Steps: list services from registry/gateway, layer them by entry point, group by domain using database ownership, draw real call relations from logs, colour‑code stability, and finally output a global view plus a detailed sub‑domain view. Scenario 2 – New Business Integration : For a new feature (e.g., points system), first sketch the existing skeleton, then add new services highlighted with dashed boxes or yellow, clearly show reuse of old services via solid lines, avoid direct DB access from new services, and outline a phased evolution (phase 1 core flow, phase 2 performance optimisation, phase 3 scenario expansion). 7. Common Pitfalls One‑to‑one mapping of business boxes to micro‑services leads to duplicated logic (e.g., separate services for scan‑pay, payment‑code, and receipt‑code). Ignoring data ownership causes services to read/write other services’ databases, breaking deployment independence. “Anemic” architecture where services are merely CRUD layers and business logic is scattered, resulting in long call chains. Failing to indicate evolution paths; use dashed boxes for planned services and grey for decommissioned ones. Remember: the left side of the diagram should be the business architecture, the right side the team topology; each service box represents both a business capability and a team responsibility.