GizToy Core Packages Documentation

This directory contains design documents, implementation notes, and known issues for all GizToy core packages. Library docs live under docs/lib/.

Documentation Structure

Each module has its own directory under docs/lib/ with the following files:

graph LR
    subgraph mod["lib/{mod}/"]
        doc[doc.md<br/>Design & Features]
        go[go.md<br/>Go Implementation]
        rust[rust.md<br/>Rust Implementation]
        issues[issues.md<br/>Known Issues]
        submod["{submod}/<br/>Submodules"]
    end

Package List

Foundation Layer

Audio Processing Layer

API Client Layer

Communication Layer

AI Application Layer

Examples

• examples: Directory structure and how to run the samples

Directory Structure

graph TB
    subgraph docs["docs/"]
        outline[outline.md]
        pkg[packages-comparison.md]
        
        subgraph examples["examples/"]
            exdoc[doc.md]
        end
        
        subgraph lib["lib/"]
            buffer[buffer/]
            encoding[encoding/]
            jsontime[jsontime/]
            trie[trie/]
            cli[cli/]
            
            subgraph audio["audio/"]
                adoc[doc.md, go.md, rust.md, issues.md]
                codec[codec/]
                pcm[pcm/]
                resampler[resampler/]
                opusrt[opusrt/]
                portaudio[portaudio/]
                songs[songs/]
            end
            
            minimax[minimax/]
            dashscope[dashscope/]
            doubaospeech[doubaospeech/]
            jiutian[jiutian/]
            mqtt0[mqtt0/]
            chatgear[chatgear/]
            speech[speech/]
            genx[genx/]
        end
        
        esp[esp/]
        bazel[bazel/]
    end

Other Documentation

Implementation Progress Overview

Legend

• ✅ Fully implemented
• ⚠️ Partially implemented
• ❌ Not implemented

Feature Comparison

Priority Recommendations

P0 - Critical Missing

1. genx/agent (Rust): Agent framework is core functionality
2. audio/opusrt OGG R/W (Rust): Required for realtime audio streaming

P1 - Feature Parity

1. doubaospeech v2 (Rust): New API version support
2. genx streaming/tools (Rust): Complete base functionality

P2 - Enhancements

1. audio/portaudio (Rust): Audio I/O support
2. mqtt0 MQTT 5.0: Complete protocol support

Work Methodology

File-by-File Review Process

For each module, the documentation is generated through a rigorous file-by-file review process:

flowchart TB
    A["1. LIST all source files"] --> B["2. READ each file carefully"]
    B --> C["3. ANALYZE for potential issues"]
    C --> D["4. DOCUMENT findings"]
    
    A1["Go: go/pkg/{mod}/*.go"] --> A
    A2["Rust: rust/{mod}/src/*.rs"] --> A
    
    C1["Race conditions"] --> C
    C2["Resource leaks"] --> C
    C3["Error handling gaps"] --> C
    C4["API inconsistencies"] --> C
    
    D1["doc.md"] --> D
    D2["go.md"] --> D
    D3["rust.md"] --> D
    D4["issues.md"] --> D

Issue Classification

Issues discovered during review are classified by severity:

Review Checklist

For each source file, the following aspects are checked:

Correctness

• Logic errors and edge cases
• Off-by-one errors in loops/slices
• Nil/None handling
• Integer overflow/underflow

Concurrency

• Data races (shared mutable state)
• Deadlock potential
• Channel/mutex usage correctness
• Proper synchronization

Resource Management

• File/socket handle leaks
• Memory leaks (especially in FFI)
• Goroutine/task leaks
• Proper cleanup in error paths

Error Handling

• Ignored errors (Go: _ = err, Rust: .unwrap())
• Error propagation correctness
• Panic vs error decision
• Context/cause preservation

API Design

• Go/Rust parity
• Consistent naming
• Proper visibility (pub/private)
• Documentation completeness

Performance

• Unnecessary allocations
• Excessive copying
• Algorithm complexity
• Buffer sizing

Security

• Input validation
• Injection vulnerabilities
• Credential handling
• Cryptographic correctness

Related Resources

• External API documentation: lib/minimax/api/, lib/dashscope/api/, lib/doubaospeech/api/
• Issue tracking: issues/
• Example code: examples/go/, examples/rust/