Skip to content

Design

kazunoko is built with a layered architecture, where each layer has a distinct responsibility. Higher layers are closer to the user (easier to use), while lower layers are closer to the hardware (more flexible).

Architecture Overview

┌─────────────────────────────────────┐
│           CLI Layer                 │  kazunoko <command>
│         (cli.py, options.py)        │
├─────────────────────────────────────┤
│        Measurement Layer            │  Reader, Measure, Streamer
│           (measure.py)              │
├─────────────────────────────────────┤
│         Command Layer               │  Command
│           (command.py)              │
├─────────────────────────────────────┤
│          Device Layer               │  PortDevice, MockDevice
│       (device.py, mock.py)          │
├─────────────────────────────────────┤
│          Parser Layer               │  DeviceResponse, ResponseParser
│           (parser.py)               │
└─────────────────────────────────────┘
Layer Module Role
CLI cli.py, options.py User-facing commands
Measurement measure.py Event streaming and session management
Command command.py High-level device API
Device device.py, mock.py Serial communication
Parser parser.py JSONL parsing and validation

Supporting modules: formatter.py (output formatting), exceptions.py (error hierarchy), workspace.py (file path resolution), history.py (command lifecycle), log.py (structured logging), doctor.py (diagnostics).

Data Flow

A cmd.status() call traverses all layers:

sequenceDiagram
    participant User
    participant Command
    participant PortDevice
    participant Hardware
    participant Parser

    User->>Command: cmd.status()
    Command->>PortDevice: device.query("GET_STATUS")
    PortDevice->>Hardware: "GET_STATUS\n" (serial)
    Hardware-->>PortDevice: {"type":"response","status":"ok",...}
    PortDevice->>Parser: parse_jsonl(line)
    Parser-->>PortDevice: DeviceResponse
    PortDevice-->>Command: DeviceResponse
    Command-->>User: DeviceResponse

Module Design Pages