Skip to content

Home

Jump to bottom
Santanu Sarkar edited this page May 29, 2026 · 1 revision

Project Codex Vanguard

Welcome to the official documentation for Project Codex Vanguard. This project is a highly scalable, platform-agnostic UI and core engine framework built natively on Kotlin Multiplatform (KMP).

🏗 Architecture & Design Principles

The architecture is driven by the principle of Extreme Separation of Concerns, ensuring absolute decoupling between business logic, state management, and user interfaces.

The "Heart/Brain" Split

The core math engine and control logic ("Brain") are strictly isolated from the UI layer ("Heart").

  • Zero-Dependency Shared Logic: The :shared module contains pure Kotlin domain logic with zero platform-specific (e.g., Android framework) dependencies.
  • Unified Design System: The :sharedUI module hosts Jetpack Compose UI components that are consumed seamlessly across both Android and Native Windows environments, eliminating UI duplication.

Unidirectional Data Flow (UDF)

State management follows strict Unidirectional Data Flow principles:

  • EventLink Interface: Decouples UI from Worker logic. Direct worker instantiation inside UI components is prohibited.
  • StateFlow Integration: Centralized state managers (LocalManager, EventManager) expose immutable UI states (LocalUiState, EventStatus).

📦 Modular Infrastructure

The repository is structured into distinct, highly cohesive modules to accelerate build times and enforce architectural boundaries:

Module Responsibility
:shared Platform-agnostic domain logic, pure math engines.
:sharedUI Multiplatform Jetpack Compose design system and UI components.
:app The Android application entry point and execution sandbox.
:desktopApp The standalone Native Windows (JVM) application entry point.
:Wave_Engine A dedicated library submodule for advanced audio processing and visualization.
:sensoryUnit KMP module handling platform-specific hardware/sensor bridging (Android, iOS).

⚙️ Key Technical Subsystems

1. High-Performance Graphics & UI

  • Compose Canvas Particle Engine: Features a responsive 2D starfield particle engine capable of rendering asynchronously at 60fps. Utilizes a low-overhead state metronome pattern (LaunchedEffect, withFrameMillis) for efficient canvas recompositions.
  • Dynamic Scaling: Device-agnostic scaling logic maps a virtual 2000x2000 grid to any physical screen size.
  • Schwarzschild Radius Mechanics: Advanced particle trajectory math (handling event horizons) is separated entirely from the Compose layer.

2. Audio Processing Pipeline

  • Scoped Audio Streaming: The AudioSource interface provisions a standardized SharedFlow for raw 16-bit PCM audio chunks.
  • Platform-Agnostic Activation: The AudioPlatformLink orchestrates specific threaded execution logic via ExecuteAudioAndroid and ExecuteAudioWindows.
  • Amplitude Tracking: The AmplitudeTracker smooths and tracks audio amplitude peaks for real-time visual feedback via the new AIScreenWave component.

🚀 Platform Support & Distribution

Project Codex Vanguard has successfully graduated from the Android UI testing sandbox and is actively deploying across multiple platforms.

  • Android: Native execution targeting modern Android SDKs.
  • Windows (JVM): Native Windows execution utilizing JetBrains Compose Desktop. Pre-configured for native .exe and .msi distributions with ProGuard obfuscation and optimization.
  • iOS (Experimental): Initial Platform.ios.kt implementation established within the :sensoryUnit module.

This wiki is dynamically maintained to reflect the master branch architecture.

Clone this wiki locally