# 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.