vitepress-template

Appearance

Architectural Enforcement and Consistency ​

**Referenced Files in This Document** - [[go.work]](file/go.work) - [[bi-template PRD]](file/bi-template/docs/prd-bi-template.md) - [[bi-common go.mod]](file/bi-common/go.mod) - [[bi-basic validation errors]](file/bi-basic/api/sd-order/v1/sd-order.pb.validate.go) - [[bi-tenant validation errors]](file/bi-tenant/api/tenant-m/v1/package.pb.validate.go) - [[BMA-D Game Architecture Checklist]](file/bmad/bmgd/workflows/3-technical/game-architecture/checklist.md) - [[BMA-D Step 08 Validation]](file/bmad/bmgd/workflows/3-technical/game-architecture/steps/step-08-validation.md) - [[BMB Validation Design Check]](file/bmad/bmb/workflows/workflow/steps-v/step-06-validation-design-check.md) - [[BMB Instruction Style Check]](file/bmad/bmb/workflows/workflow/steps-v/step-07-instruction-style-check.md) - [[BMM Architectural Patterns Research]](file/bmad/bmm/workflows/1-analysis/research/technical-steps/step-04-architectural-patterns.md) - [[BMA-D Risk Governance and Gatekeeping]](file/bmad/bmm/testarch/knowledge/risk-governance.md) - [[Qwen NFR Assess Task]](file/.qwen/commands/bmad/tasks/nfr-assess.toml) - [[BMA-D NFR Criteria]](file/bmad/bmm/testarch/knowledge/nfr-criteria.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
  10. Appendices

Introduction ​

This document explains how architectural consistency is enforced across the 19-service ecosystem. It covers:

  • Monorepo management via go.work and module dependencies
  • Bi-template scaffolding for consistent service creation
  • Code generation standards and dependency validation
  • Architectural gatekeeping, anti-pattern detection, and automated quality gates
  • Governance patterns, code review processes, and architectural decision documentation
  • Third-party dependency evaluation and adoption practices

Project Structure ​

The ecosystem is organized as a Go workspace with 19 modules. The workspace coordinates builds and cross-service imports while each module encapsulates a microservice or shared library.

Diagram sources

Section sources

Core Components ​

  • Workspace coordination: go.work defines the 19-service monorepo and Go toolchain version.
  • Shared foundation: bi-common provides standardized infrastructure (logging, tracing, database, Redis, Kafka, gRPC, Nacos, JWT).
  • Service scaffolding: bi-template defines the canonical layered architecture and generation pipeline.
  • Validation and governance: BMA-D workflows and BMM knowledge capture enforce architectural coherence, anti-pattern detection, and quality gates.

Section sources

Architecture Overview ​

The ecosystem enforces consistency through:

  • Canonical layered architecture (Service/Biz/Data) with strict separation of concerns
  • Centralized dependency injection via Wire
  • Unified error handling and response types via bi-common/apitypes
  • Generated validation and OpenAPI artifacts from Protobuf definitions
  • Architectural gatekeeping via BMA-D workflows and BMM knowledge

Diagram sources

Detailed Component Analysis ​

Bi-Template System: Consistent Service Scaffolding ​

The bi-template establishes the canonical structure and generation pipeline:

  • Layered architecture: Service (API interface), Biz (domain logic), Data (persistence)
  • Dependency injection: enforced via google/wire
  • Naming convention: service entry under cmd/[service-name]/main.go
  • Generation commands: init, generate, build
  • Infrastructure integration: Nacos, logging/tracing, JWT, MySQL/Redis

Diagram sources

Section sources

Code Generation Standards and Validation ​

  • Protobuf-driven generation produces API interfaces, validation code, and OpenAPI artifacts.
  • Validation errors are generated per message with multi-error aggregation and field-specific diagnostics.
  • Example validation artifacts:
    • bi-basic: multi-error types and validation errors for SD order imports
    • bi-tenant: multi-error types and validation errors for tenant packages

Diagram sources

Section sources

Architectural Gatekeeping and Anti-Pattern Detection ​

  • BMA-D Game Architecture Checklist: Validates completeness, practicality, and readiness before implementation.
  • BMA-D Step 08 Validation: Ensures architectural coherence and guides fixing gaps prior to implementation.
  • BMB Validation Design Check: Enforces rigorous, systematic validation step design with anti-lazy mandates and critical flow segregation.
  • BMB Instruction Style Check: Requires deep, thorough instruction analysis across all step files with auto-proceed mechanisms.

Diagram sources

Section sources

Automated Quality Gates and Risk Governance ​

  • Risk Governance and Gatekeeping: Formal risk scoring (probability × impact), classification by category, and mitigation ownership to transform subjective “should we ship?” into objective decisions.
  • Non-Functional Requirements (NFR) Criteria: NFRs validated through automated tests with measurable thresholds; ambiguous requirements default to CONCERNS until clarified.
  • Qwen NFR Assess Task: Interactive/non-interactive assessment of NFRs (security, performance, reliability, maintainability) with threshold collection and gate YAML generation.

Diagram sources

Section sources

Conceptual Overview ​

  • Architectural patterns research: BMM’s technical research step documents current best practices and design principles for informed decisions.
  • Governance patterns: Risk scoring, coverage traceability, and acceptance criteria mapping form quality gates.

Diagram sources

Section sources

Dependency Analysis ​

The workspace coordinates 19 modules with a shared Go toolchain. bi-common centralizes infrastructure dependencies (logging/tracing, DB/Redis/Kafka, gRPC, Nacos, JWT), ensuring consistent behavior across services.

Diagram sources

Section sources

Performance Considerations ​

  • Prefer generated validation and OpenAPI artifacts to reduce runtime overhead and improve correctness.
  • Use bi-common’s standardized observability stack (logging, tracing, metrics) for consistent monitoring.
  • Keep layered architecture boundaries intact to enable targeted optimization and testing.

Troubleshooting Guide ​

Common architectural rule violations and resolution patterns:

  • Violation: Deviates from layered architecture (mixing persistence logic in Service layer)
    • Resolution: Move persistence logic to Data layer and keep Service layer as API interface
  • Violation: Bypasses Wire DI
    • Resolution: Add Wire setup and remove ad-hoc instantiations
  • Violation: Ignores generated validation
    • Resolution: Regenerate Protobuf artifacts and integrate validation errors
  • Violation: Missing NFR coverage
    • Resolution: Define thresholds, add automated tests, and update NFR assessment

Section sources

Conclusion ​

The ecosystem enforces architectural consistency through:

  • A canonical bi-template with layered architecture and generation pipeline
  • Centralized infrastructure via bi-common
  • Robust validation and governance via BMA-D and BMM workflows
  • Automated quality gates grounded in risk scoring and NFR criteria

Adopting new technologies requires adherence to these patterns and gatekeeping processes to preserve consistency and reliability.

Appendices ​

  • Governance and code review processes: Use BMA-D checklists and validation steps as mandatory pre-implementation gates; integrate Qwen NFR assessments for automated quality checks.
  • Third-party dependency evaluation: Evaluate compatibility with bi-common infrastructure and ensure adoption does not violate architectural constraints.