Mizuki Build & Test Architecture

1. Overview

Mizuki is a polyglot, multi-service system composed of several core services, clients, and external dependencies.
The build system must:

  • Support Python, C++, and potentially other languages.

  • Handle compiled external libraries using their native build systems.

  • Allow clear separation of source, tests, and staging deployment.

  • Use SCons as the top-level orchestrator, delegating to CMake (or others) for external dependencies.

  • Provide unit, component, integration, and system testing capabilities.

2. Services and Clients

Core Services

  • FileManipulator — Handles file operations.

  • ProjectExplorer — Manages project structures and metadata.

  • EDDI — Specialized domain-specific processing engine.

  • Glotty — Localization and translation service.

Clients

  • TerminalClient — CLI interface for Mizuki.

  • MizukiCockpit — GUI dashboard and control center.

3. External Dependencies

External libraries are stored in external/ and built using their native build systems.

Examples:

  • NATS (messaging middleware) — CMake build.

  • Other libraries to be added as needed.

4. Directory Structure

mizuki/
│
├── build/                     # All build artifacts
│   ├── scons/                  # SCons build cache
│   └── staging/                # "Install" area for testing & packaging
│       └── windows
│       │   └── bin             # Here we store the binaries
│       │   └── res             # Here we store the resources
│       │   └── cfg             # Here we store the configurations
│       └── linux
│   ├── testlibs/               # Build results for testing (pr platform target)
│   │   └── windows/            # One area for each platform
│
│
├── external/                   # External libraries
│   ├── lib/
│   ├── include/
│   ├── nats/                   # NATS source, built with CMake
│   └── ...
│
├── services/                   # Mizuki services
│   ├── FileManipulator/
│   │   ├── src/                # Production source code
│   │   ├── include/            # Public headers
│   │   └── SConscript
│   ├── ProjectExplorer/
│   │   ├── src/
│   │   ├── include/
│   │   └── SConscript
│   ├── EDDI/
│   ├── Glotty/
│   └── ...
│
├── clients/                    # Mizuki clients
│   ├── TerminalClient/
│   │   ├── src/
│   │   └── SConscript
│   └── MizukiCockpit/
│
├── tests/                      # All tests
│   ├── unit/
│   │   ├── FileManipulator/
│   │   ├── ProjectExplorer/
│   │   └── ...
│   ├── component/
│   │   ├── FileManipulator/
│   │   └── ProjectExplorer/
│   ├── integration/
│   └── system/
│
├── scripts/                    # Helper scripts for dev & CI/CD
│   ├── build_all.py
│   ├── run_tests.py
│   ├── deploy_staging.py
│   └── ...
│
└── SConstruct                  # Top-level build orchestrator

5. Build Strategy

5.1 SCons as the Orchestrator

  • The top-level SConstruct coordinates:

    1. Build external dependencies (via native build systems like CMake).

    2. Build each service/client as a library and/or executable.

    3. Install outputs into build/staging/.

5.2 External Libraries

  • Placed in external/.

  • Each external library has:

    • Its own native build invocation (cmake .. && make).

    • A staging install path inside build/staging/.

5.3 Services and Clients

  • Core logic built into a library (libServiceName.a or .so).

  • Service executables link against their own libraries.

  • Unit/component test binaries also link against the same libraries.

6. Testing Strategy

6.1 Test Types

  • Unit tests
    Test individual functions/classes. Link directly against the service library with mocks.

  • Component tests
    Test a single service with real dependencies (e.g., FileManipulator with real file I/O).

  • Integration tests
    Test multiple services working together in a coordinated environment.

  • System tests
    Test the entire deployed staging installation as a black box.

6.2 Test Build Model

Key principle:
Services are compiled into libraries, which are then linked into:

  • The service executable (for production)

  • One or more test executables (for testing)

Example:

libFileManipulator.a
├── file_ops.cpp
├── path_utils.cpp
└── ...

Unit test binary:

test_FileManipulator
  Links: libFileManipulator.a + GoogleTest

6.3 Test Execution Model

  • Each service produces:

    • service_name → production executable.

    • test_service_name → test executable for unit/component tests.

Run order for CI/CD:

  1. Build external dependencies.

  2. Build all service libraries.

  3. Build and run all unit tests (fast fail).

  4. Build and run component tests.

  5. Build staging install (build/staging/).

  6. Run integration tests.

  7. Run system tests against staging.

7. Staging Installation

  • The build/staging/ directory mirrors the real installation layout:

build/staging/
├── bin/           # Executables
├── lib/           # Libraries
├── share/         # Resources
└── etc/           # Config files

  • System tests operate against this staging installation to validate deployment readiness.

  • This also serves as the packaging source for release builds.

8. Tooling & Frameworks

  • Build systems:

    • Top-level: SCons

    • External deps: Native (CMake, Make, etc.)

  • Test frameworks:

    • GoogleTest for C++ tests.

    • pytest for Python components.

  • Orchestration:

    • scripts/run_tests.py to run all test levels in order.

    • scripts/build_all.py to build everything from scratch.

9. Benefits of This Approach

  • Clean separation of production code and tests.

  • Unified top-level build via SCons.

  • Native builds for external dependencies without rewriting.

  • Reproducible staging area for system tests and packaging.

  • Incremental builds possible for faster development cycles.