vitepress-template

Appearance

Service Architecture Patterns and Boundaries ​

**Referenced Files in This Document** - [[bi-analysis/cmd/bi-analysis/main.go]](file/bi-analysis/cmd/bi-analysis/main.go) - [[bi-analysis/cmd/bi-analysis/wire.go]](file/bi-analysis/cmd/bi-analysis/wire.go) - [[bi-basic/cmd/server/main.go]](file/bi-basic/cmd/server/main.go) - [[bi-api-jushuitan/cmd/bi-api-jushuitan/main.go]](file/bi-api-jushuitan/cmd/bi-api-jushuitan/main.go) - [[bi-api-leke/cmd/bi-api-leke/main.go]](file/bi-api-leke/cmd/bi-api-leke/main.go) - [[bi-notify/cmd/bi-notify/main.go]](file/bi-notify/cmd/bi-notify/main.go) - [[bi-sys/cmd/bi-sys/main.go]](file/bi-sys/cmd/bi-sys/main.go) - [[bi-chat/bi_chat/main.py]](file/bi-chat/bi-chat/main.py) - [[bi-common/registry/nacos/client.go]](file/bi-common/registry/nacos/client.go) - [[bi-analysis/internal/biz/README.md]](file/bi-analysis/internal/biz/readme.md) - [[bi-basic/internal/biz/README.md]](file/bi-basic/internal/biz/readme.md) - [[bi-notify/internal/biz/README.md]](file/bi-notify/internal/biz/readme.md)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document explains the 19-service microservices ecosystem and the standardized Service-Biz-Data layered architecture adopted across Go services. It documents how Kratos framework standardizes service structure, dependency injection via Wire, and lifecycle management. It also outlines decomposition principles, DDD boundaries, and cross-cutting concerns separation. Concrete examples are drawn from bi-server orchestrator, bi-analysis analytics engine, bi-basic foundation services, and specialized services like bi-chat and bi-notify. Strategies to avoid tight coupling and maintain clean boundaries are detailed.

Project Structure ​

The ecosystem follows a consistent monorepo workspace with multiple services under dedicated directories. Each Go service adheres to the Service-Biz-Data layered pattern and uses Kratos for transport, configuration, logging, and service registration. Python-based bi-chat uses FastAPI with AgentScope for multi-agent orchestration.

Diagram sources

Section sources

Core Components ​

  • Service-Biz-Data layered architecture:
    • Service layer exposes transport APIs (gRPC/HTTP) and delegates to Biz.
    • Biz layer encapsulates business logic and orchestrates Data.
    • Data layer handles persistence, external clients, and repositories.
  • Kratos adoption:
    • Standardized transport servers, configuration loading, logging/tracing, and service registration.
    • Dependency injection via Wire provider sets per layer.
  • Cross-cutting concerns:
    • Nacos for configuration and service discovery.
    • Observability (logging/tracing).
    • Kafka consumers/producer managers for event streaming.
    • Snowflake ID generation.

Examples by service:

  • bi-analysis: Analytics engine with SQL builders, validators, and templates.
  • bi-basic: Foundation services for orders, goods, shops, costs, and Kafka ingestion.
  • bi-api-jushuitan and bi-api-leke: External API adapters with Kafka consumers.
  • bi-notify: Notification engine with channel adapters and template engine.
  • bi-sys: System orchestration with registrar and lifecycle hooks.
  • bi-chat: Multi-agent chat powered by FastAPI and AgentScope.

Section sources

Architecture Overview ​

The architecture enforces consistent patterns across services:

  • Entry point initializes Kratos app with gRPC/HTTP servers, logger, and optional registrar.
  • Configuration loaded from Nacos; bootstrap struct defines service name/version.
  • Wire provider sets assemble dependencies for Server, Data, Biz, and Service layers.
  • Optional Kafka consumers are started during app lifecycle.

Diagram sources

Detailed Component Analysis ​

bi-analysis: Analytics Engine ​

Responsibilities:

  • Provides analytical metadata, dimensions, fields, and templates.
  • Implements SQL builder and validators for safe query construction.
  • Exposes gRPC/HTTP endpoints via Service layer.

Layered structure:

  • Service: API handlers and gRPC bindings.
  • Biz: Business logic for templates, queries, and validations.
  • Data: Models and clients for underlying storage.

Diagram sources

Section sources

bi-basic: Foundation Services ​

Responsibilities:

  • Core domain entities: orders, goods, shops, categories, costs.
  • Async processing and Kafka ingestion/egress.
  • Shared business logic and repositories.

Diagram sources

Section sources

bi-api-jushuitan and bi-api-leke: External API Adapters ​

Responsibilities:

  • Adapter services for external systems (Jushuitan, Leke).
  • Register HTTP/gRPC handlers and start multiple Kafka consumers via ConsumerManager.

Diagram sources

Section sources

bi-notify: Notification Engine ​

Responsibilities:

  • Multi-channel notifications (email, SMS, DingTalk, Feishu).
  • Template engine and routing; Kafka consumer for incoming events.
  • Lifecycle hooks to start/stop consumers gracefully.

Diagram sources

Section sources

bi-sys: System Orchestration ​

Responsibilities:

  • Centralized system registrar and lifecycle management.
  • Snowflake ID initialization with Nacos-aware configuration.

Diagram sources

Section sources

bi-chat: Multi-Agent Chat (Python) ​

Responsibilities:

  • FastAPI-based chat service with AgentScope multi-agent orchestration.
  • Lifespan manages shared model/toolkit initialization and periodic session cleanup.

Diagram sources

Section sources

Dependency Analysis ​

Cross-cutting concerns and coupling avoidance:

  • Nacos integration centralizes configuration and service discovery across services.
  • bi-common provides shared modules for registry, observability, MQ, and utilities.
  • Kratos standardizes transport and lifecycle across services.
  • Wire provider sets enforce layer boundaries and DI.

Diagram sources

Section sources

Performance Considerations ​

  • Use Kratos servers efficiently; configure concurrency and resource limits per environment.
  • Centralize configuration via Nacos to enable dynamic tuning without redeployments.
  • Apply Snowflake ID generation consistently to avoid contention and ensure uniqueness.
  • For Kafka-heavy services, tune consumer workers and batch sizes according to throughput needs.
  • Enable observability instrumentation to monitor latency, error rates, and hotspots.

Troubleshooting Guide ​

  • Configuration loading failures: Verify application-<env>.yaml availability and correctness; confirm Nacos endpoint reachability.
  • Service registration issues: Check Nacos credentials and namespace settings; ensure registrar is initialized.
  • Kafka consumer startup errors: Validate broker addresses, topics, and consumer groups; inspect consumer manager configuration.
  • Logging/tracing not appearing: Confirm logger setup and environment variables; ensure proper log level configuration.
  • Dependency injection errors: Review Wire provider sets and ensure all constructors are bound.

Section sources

Conclusion ​

The 19-service ecosystem leverages a consistent Service-Biz-Data layered architecture and Kratos framework to achieve scalable, maintainable, and observable microservices. Cross-cutting concerns are centralized via bi-common, while domain-driven decomposition keeps services cohesive and loosely coupled. The documented patterns—configuration, transport, DI, lifecycle, and event streaming—enable reliable operations and predictable evolution across the platform.