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:
```bash
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