Service Overview and Architecture
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document provides a comprehensive overview of bi-server's architecture and design patterns within the BI Analysis Platform. It explains bi-server's role as the central business orchestration hub coordinating microservices such as bi-analysis, bi-basic, bi-chat, and bi-notify. The document details the layered architecture pattern (biz/data/service), dependency injection principles via Google Wire, and service composition strategies. It also describes the main entry point structure, initialization sequence, and shutdown procedures, along with architectural diagrams illustrating service relationships and data flow patterns.
Project Structure
The bi-server module defines a set of protocol buffer APIs that serve as the contract surface for external consumers and internal services. These APIs are organized by domain and version, enabling clear separation of concerns and consistent evolution across the platform.
Key characteristics:
- Module definition and Go version alignment
- Protocol buffer generation targets for gRPC, HTTP, validation, and OpenAPI
- Replacement directives for local development and cross-module references
Diagram sources
Section sources
Core Components
bi-server exposes domain-specific gRPC/HTTP services through protocol buffers. Two representative examples illustrate the service design:
- bi_api_jushuitan/v1/inventory: Provides asynchronous and synchronous inventory fetch operations for an external e-commerce system.
- bi_leke/v1/order: Exposes order synchronization endpoints for a marketplace platform, including full and incremental sync, refund retrieval, and order info updates.
These services define:
- RPC method contracts with HTTP annotations for REST-like access
- Request/response messages with validation rules
- OpenAPI metadata for documentation and tooling
Diagram sources
Section sources
Architecture Overview
bi-server operates as the central orchestrator for the BI Analysis Platform. It defines the canonical API contracts that downstream services implement and consumers invoke. The platform follows a layered architecture pattern:
- biz (business logic)
- data (persistence and external integrations)
- service (composition and orchestration)
Dependency injection is achieved via Google Wire, enabling modular assembly of servers, registries, Kafka consumers, and business components. The typical lifecycle includes:
- Parsing runtime flags and loading configuration from Nacos
- Setting up logging and observability
- Wiring components with Wire
- Starting Kratos servers and running the application
Diagram sources
Section sources
Detailed Component Analysis
Layered Architecture Pattern (biz/data/service)
The platform employs a clean layered architecture:
- biz encapsulates domain logic and use cases
- data handles persistence and external system integrations
- service composes biz and data layers and exposes cohesive operations
This separation enables:
- Testability through interface-based design
- Independent evolution of layers
- Clear responsibility boundaries
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
Dependency Injection with Google Wire
Wire is used to assemble the application:
- A provider set aggregates constructors for servers, registries, and components
- wireApp builds the Kratos application with injected dependencies
- The composition is declarative and reduces boilerplate
Diagram sources
Section sources
Main Entry Point and Initialization Sequence
The main entry point orchestrates configuration loading, logging setup, dependency wiring, and application startup. The sequence ensures:
- Environment-specific configuration is loaded from Nacos
- Logging is configured before any operation
- Wire composes all dependencies
- Kratos runs the gRPC and HTTP servers
Diagram sources
Section sources
Shutdown Procedures
Shutdown is managed by Kratos, which gracefully stops servers and triggers cleanup functions returned by wireApp. This ensures:
- Proper resource release
- Graceful termination of background workers (e.g., Kafka consumers)
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
Dependency Analysis
bi-server depends on Kratos for transport and application lifecycle management, and on bi-common for shared infrastructure like configuration, logging, and service discovery. The module replaces local paths for development, ensuring consistent builds across the workspace.
Diagram sources
Section sources
Performance Considerations
- Use HTTP annotations for REST-friendly endpoints while retaining gRPC efficiency
- Apply validation rules in protobuf definitions to reduce runtime checks
- Centralize configuration via Nacos to enable dynamic tuning without redeployments
- Employ Kratos servers for efficient concurrency and graceful shutdown
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common operational issues and resolutions:
- Configuration loading failures: Verify Nacos configuration files and environment flags
- Logging misconfiguration: Ensure logger initialization precedes any logging calls
- Wire assembly errors: Confirm provider sets include all required constructors
- Server startup failures: Check port availability and transport configurations
Section sources
Conclusion
bi-server serves as the central business orchestration hub for the BI Analysis Platform. Its layered architecture, dependency injection with Wire, and clear initialization sequence enable scalable, maintainable service composition. By defining robust API contracts and integrating with platform services like bi-basic, bi-analysis, bi-chat, and bi-notify, bi-server facilitates seamless coordination across the ecosystem.