vitepress-template

Appearance

Architecture and Design ​

**Referenced Files in This Document** - [[main.go]](file/bi-basic/cmd/server/main.go) - [[wire.go]](file/bi-basic/cmd/server/wire.go) - [[server.go]](file/bi-basic/internal/server/server.go) - [[grpc.go]](file/bi-basic/internal/server/grpc.go) - [[http.go]](file/bi-basic/internal/server/http.go) - [[kafka.go]](file/bi-basic/internal/server/kafka.go) - [[data.go]](file/bi-basic/internal/data/data.go) - [[biz.go]](file/bi-basic/internal/biz/biz.go) - [[service.go]](file/bi-basic/internal/service/service.go) - [[conf.proto]](file/bi-basic/app/service/internal/conf/conf.proto) - [[application-dev.yaml]](file/bi-basic/configs/application-dev.yaml) - [[go.mod]](file/bi-basic/go.mod)

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 describes the foundational data services layer of bi-basic, focusing on the layered architecture pattern separating server, business (biz), and service layers. It explains Kratos framework integration, dependency injection via Google Wire, and the service initialization flow. It also documents business logic organization, data access patterns, cross-cutting concerns, system boundaries, and integration with external systems such as Nacos, Kafka, and StarRocks-compatible databases. Finally, it outlines design principles, architectural decisions, and scalability considerations for the foundational layer.

Project Structure ​

The bi-basic module follows a clean, layered structure:

  • cmd/server: Application entrypoint, Kratos app assembly, and Wire DI bootstrap.
  • internal/server: Transport servers (gRPC/HTTP), registration, discovery, and Kafka consumer.
  • internal/service: Service implementations exposing APIs to clients.
  • internal/biz: Business logic layer orchestrating use cases and coordinating repositories.
  • internal/data: Data access layer, repositories, transactions, and external clients.
  • app/service/internal/conf: Configuration schema for runtime bootstrap.
  • configs: Environment-specific configuration sources (YAML/Nacos).
  • docs: Domain and integration documentation.

Diagram sources

Section sources

Core Components ​

  • Kratos App lifecycle: initialized with servers, logger, registry, and cleanup hooks.
  • Dependency Injection: Wire provider sets assemble server, data, biz, and service components.
  • Transport Servers: gRPC and HTTP servers configured with middleware and service registrations.
  • Data Access: Centralized Data struct manages DB and Redis clients, transaction helpers, and repository wiring.
  • Business Logic: Biz layer composes use cases and delegates to repositories.
  • Service Layer: Exposes domain services to clients via generated APIs.
  • Kafka Consumer: Asynchronous event processing with configurable topics and workers.
  • Configuration: Bootstrap proto defines server, data, and logging configuration; Nacos YAML sources provide runtime config.

Section sources

Architecture Overview ​

The system adheres to layered architecture:

  • Presentation/Transport Layer: Kratos gRPC and HTTP servers register generated services.
  • Service Layer: Implements business-facing APIs and delegates to biz.
  • Business Layer: Encapsulates domain use cases and coordinates repositories.
  • Data Access Layer: Provides repositories, transactions, and external clients.
  • Cross-Cutting Concerns: Logging, recovery, validation, metadata, auth, and observability.

Diagram sources

Detailed Component Analysis ​

Kratos Initialization and Dependency Injection ​

  • Entry point parses environment flag and loads Nacos-configured YAML.
  • Scans Bootstrap proto to populate runtime configuration.
  • Uses Wire to construct Kratos app with server, data, biz, and service provider sets.
  • Starts Kafka consumer concurrently and runs Kratos app.

Diagram sources

Section sources

Transport Servers: gRPC and HTTP ​

  • gRPC server registers multiple generated services and applies middleware (recovery, validator, logging, metadata, auth).
  • HTTP server registers services, custom routes, and middleware (request ID, logging, recovery, validator, metadata, remote auth).
  • Remote authentication integrates with bi-tenant via gRPC to validate tokens and inject user info into context.
  • Custom endpoints include SSE streaming and template downloads.

Diagram sources

Section sources

Data Access Layer and Transactions ​

  • Data struct encapsulates DB and Redis clients, with initialization supporting Redis cluster address mapping.
  • Provides transaction helpers: Transaction and InTx, and a GetDB helper that prefers an active transaction from context.
  • Repository wiring aggregates multiple repos under RepoImpl and exposes individual repo constructors for DI.

Diagram sources

Section sources

Business Logic Organization ​

  • Biz provider set wires multiple use-case logics (goods, shop, category, orders, costs, invalid orders, SD orders, repeat shopping, out orders).
  • Biz layer coordinates repositories and orchestrates domain workflows without direct transport coupling.

Section sources

Service Layer Exposure ​

  • Service provider set registers numerous services (goods, shop, shop auth, categories, orders, async, cost, out orders, repeat shopping, SD orders, invalid orders, dict services).
  • Services depend on biz layer and expose generated APIs to clients.

Section sources

Kafka Consumer Integration ​

  • KafkaConsumer constructs handlers and reads topic/group/worker settings from Bootstrap config.
  • Supports dynamic topic routing and worker scaling; starts consumer loop with cancellation support.

Diagram sources

Section sources

Configuration and Environment Management ​

  • Bootstrap proto defines Server, Data, and Log structures, enabling structured runtime configuration.
  • Nacos YAML sources define namespace, group, and data IDs for centralized config management.

Section sources

Dependency Analysis ​

  • Kratos and Wire: Core frameworks for transport and DI.
  • bi-common: Shared configuration, auth, logging, database, Redis, Kafka, and gRPC utilities.
  • bi-proto: Generated APIs for services and Kafka integration.
  • External libraries: MySQL driver, gRPC, Kafka client, OpenTelemetry, and others.

Diagram sources

Section sources

Performance Considerations ​

  • Transaction Context Propagation: Use InTx and GetDB to ensure queries reuse the same transactional context, reducing overhead and maintaining consistency.
  • Redis Cluster Dialer Mapping: Local development with cluster mode uses a dialer to map internal IPs to local ports, avoiding network latency spikes during iteration.
  • Middleware Ordering: Place recovery and logging early to minimize unhandled panics and ensure observability.
  • Kafka Workers: Tune worker counts per topic to balance throughput and resource utilization.
  • HTTP Streaming: SSE endpoints should flush responses promptly to maintain responsiveness.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • Configuration Loading Failures: Verify Nacos YAML paths and data IDs; ensure environment flag matches the intended config file.
  • Authentication Failures: Confirm bi-tenant gRPC availability and token validity; check whitelist configuration for unprotected routes.
  • Kafka Consumer Issues: Validate broker lists, consumer groups, and topic configurations; confirm worker counts and commit intervals.
  • Transaction Errors: Ensure transaction context is propagated via InTx and that GetDB is used inside the transaction context.
  • Redis Connectivity: For cluster mode, confirm dialer mapping and that local port-forwarding is active.

Section sources

Conclusion ​

The bi-basic foundational data services layer cleanly separates concerns across server, biz, and service layers while integrating tightly with Kratos and Google Wire for DI. It leverages shared utilities from bi-common for configuration, auth, logging, database, Redis, and Kafka. The design supports scalable, observable, and maintainable operations, with explicit transaction handling, flexible transport servers, and asynchronous event processing via Kafka. Adhering to these patterns ensures predictable growth and robust integration with external systems.