docs/ARCHITECTURE.md

LOGOS Architecture - Clean Implementation

Overview

This repository contains the clean, production-ready LOGOS implementation stripped of "AI bloat" and focused on core functionality.

Core Components

1. logos_core.py - The Mathematical Heart

Pure math functions with no dependencies beyond standard library:

• resolve_fractal_address() - Fractal coordinate decoder
• prime_harmonizer() - Prime modulo classification
• calculate_heat_code() - Path to Heat Code encoding
• pack_atom() / unpack_atom() - Atom serialization

Key Feature: Zero external dependencies for core logic (only uses struct from stdlib).

2. bake_stream.py - The Encoder (The Baker)

Encodes images into SPCW streams:

• Adaptive quadtree decomposition
• Variance-based splitting
• Atom generation from regions
• Stream serialization

Dependencies: numpy, opencv-python

3. eat_cake.py - The Player (The Cake Consumer)

Reconstructs images from SPCW streams:

• Fractal address resolution
• Canvas state management
• Heatmap visualization mode
• Non-linear reconstruction

Dependencies: numpy, opencv-python

Architecture Philosophy

Separation of Concerns

• Core Logic (logos_core.py): Pure math, no I/O, testable in isolation
• Encoder (bake_stream.py): Image → Atoms
• Decoder (eat_cake.py): Atoms → Image

Non-Linear Processing

The key innovation is fractal addressing:

• Traditional: Sequential scan (top-to-bottom, left-to-right)
• LOGOS: Fractal descent (geometric significance determines order)

This enables:

• Compression via geometry (only active regions transmitted)
• Infinite canvas support (non-linear memory layout)
• Deterministic reconstruction (same Heat Code → same position)

Data Flow

Image (PNG) 
  → [Baker] → Atoms (512B chunks)
  → [Stream] → .spcw file
  → [Player] → Canvas State
  → [Renderer] → Reconstructed Image

Testing

Run the test pipeline:

python test_bake_eat.py

This creates a test image, bakes it, and reconstructs it to verify the complete loop.

Legacy Code

The following files are from the earlier experimental phase and can be archived:

• display_interpreter.py - Complex state engine (superseded by eat_cake.py)
• fractal_engine.py - Advanced quadtree (functionality merged into logos_core.py)
• playback_window.py - PyQt UI (superseded by OpenCV in eat_cake.py)
• main.py - Old integration script
• stream_interpreter.py - Classification engine (functionality merged)

Note: These can be kept for reference but are not needed for the clean implementation.

Extension Points

Adaptive Grid Strategies

The Baker uses quadtree (2x2 splits), but the architecture supports:

• Octree: 3x3 splits (for 3D or higher dimensions)
• Prime Grid: NxM splits based on prime modulus
• Variable Depth: Adaptive based on content complexity

Enhanced Payload Encoding

Current implementation uses average color. Could be extended to:

• Raw pixel data (for detailed regions)
• Frequency domain (DCT/FFT coefficients)
• Vector quantization
• Lossless compression

Performance Notes

• Encoding: O(N log N) where N = number of pixels (quadtree depth)
• Decoding: O(M) where M = number of atoms (linear scan)
• Memory: Canvas state is O(W×H×3) bytes

For 4K images (3840×2160):

• Raw size: ~25 MB
• Encoded (typical): ~5-10 MB (depending on content)
• Decoding time: <1 second on modern hardware

Future Work

1. StreamHarmonizer: Audio/data synchronization against Global Scalar Wave
2. Multi-resolution: Support for progressive streaming
3. GPU Acceleration: Parallel quadtree decomposition
4. Network Protocol: Stream over network with error correction