ZepraBrowser - Complete Architecture

Integration with Existing Project Structure

Current Project Location

~/Documents/zeprabrowser/

🎯 Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                      ZepraBrowser Application                    │
│                                                                  │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐ │
│  │ Tabs/UI    │  │ DevTools   │  │ Extensions │  │ Settings │ │
│  │ Manager    │  │ Native UI  │  │ Manager    │  │ Panel    │ │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └────┬─────┘ │
│        │               │               │              │        │
└────────┼───────────────┼───────────────┼──────────────┼────────┘
         │               │               │              │
         └───────────────┴───────────────┴──────────────┘
                         │
         ┌───────────────▼────────────────────┐
         │      Browser Engine (Zepra)        │
         │  • Rendering Engine                │
         │  • JavaScript Engine (ZebraScript) │
         │  • Networking Stack                │
         │  • Storage/Cache                   │
         └───────────────┬────────────────────┘
                         │
         ┌───────────────▼────────────────────┐
         │         Platform Layer             │
         │  • OS Integration                  │
         │  • GPU Acceleration                │
         │  • Process Sandboxing              │
         └────────────────────────────────────┘

📁 Integrated Project Structure

zeprabrowser/
├── CMakeLists.txt                              # ROOT BUILD
├── Architecture.md                             # Architecture docs
├── README.md
│
├── source/                                     # === NEW ARCHITECTURE ===
│   │
│   ├── ThirdParty/                            # External dependencies
│   ├── aiEngine/                              # AI integration & LLM APIs
│   ├── bin/                                   # Built executables
│   ├── devtools/                              # Developer tools, debugger GUI
│   ├── extensions/                            # Extension system & sandbox
│   ├── integration/                           # Service integrations
│   ├── main.cpp                               # Application Entry
│   ├── media/                                 # Audio/Video processing
│   ├── networking/                            # Network stack, sockets
│   ├── nxbase/                                # NeolyxOS Base components
│   ├── nxcrypto/                              # Cryptography, TLS/SSL
│   ├── nxhttp/                                # HTTP/HTTP2 parser & client
│   ├── nxjson/                                # JSON parsing & generation
│   ├── nxrender-cpp/                          # Core rendering logic (C++)
│   ├── nxsvg_wrapper.cpp                      # SVG Rendering Support
│   ├── nxxml/                                 # XML/DOM parsing
│   ├── platform/                              # Cross-platform abstractions
│   ├── privacy/                               # Privacy & tracking protection
│   ├── sandbox/                               # IPC sandboxing model
│   ├── storage/                               # LocalStorage, IndexedDB, Cache
│   ├── webCore/                               # Core layout and rendering
│   ├── webGpu/                                # WebGL & WebGPU implementation
│   ├── webapp/                                # Progressive Web PWA
│   ├── zepraEngine/                           # Browser shell & core UI
│   └── zepraScript/                           # ⚠️ JavaScript Engine Core
│
├── config/                                    # Configuration files
├── docs/                                      # Documentation
├── tools/                                     # Dev tools
└── zepra.ketivee.com/                         # Branding assets

🏗️ Component Architecture

1. Browser Core Stack

┌────────────────────────────────────────┐
│          Application Layer             │
│  • Tab Management                      │
│  • Window Management                   │
│  • User Interface                      │
│  • Settings & Preferences              │
└──────────────┬─────────────────────────┘
               │
┌──────────────▼─────────────────────────┐
│         Browser Engine Layer           │
│  ┌──────────────┐  ┌────────────────┐ │
│  │  Rendering   │  │  JavaScript    │ │
│  │  Engine      │◄─┤  Engine        │ │
│  │  (WebCore)   │  │  (ZebraScript) │ │
│  └──────┬───────┘  └────────────────┘ │
│         │                              │
│  ┌──────▼───────┐  ┌────────────────┐ │
│  │  Layout      │  │  Networking    │ │
│  │  Engine      │  │  Stack         │ │
│  └──────┬───────┘  └────────────────┘ │
│         │                              │
│  ┌──────▼───────┐  ┌────────────────┐ │
│  │  Paint       │  │  Storage       │ │
│  │  & Graphics  │  │  System        │ │
│  └──────────────┘  └────────────────┘ │
└──────────────┬─────────────────────────┘
               │
┌──────────────▼─────────────────────────┐
│          Platform Layer                │
│  • OS Integration                      │
│  • GPU Acceleration (WebGPU)           │
│  • Process Sandboxing                  │
│  • IPC (Inter-Process Communication)   │
└────────────────────────────────────────┘

2. Page Loading Pipeline

User Types URL
      ↓
Navigation Controller
      ↓
DNS Resolution
      ↓
HTTP Request → HTTP Response
      ↓
HTML Parser → DOM Tree
      ↓
CSS Parser → CSSOM Tree
      ↓
JavaScript Execution (ZebraScript)
      ↓
DOM + CSSOM → Render Tree
      ↓
Layout Engine → Layout Tree
      ↓
Paint Engine → Display List
      ↓
Compositing → GPU Layers
      ↓
Screen Display

3. Multi-Process Architecture

┌─────────────────────────────────────────────────────────┐
│                   Browser Process                        │
│  • Main UI                                              │
│  • Tab Management                                       │
│  • Network Service                                      │
│  • Storage Service                                      │
└───┬─────────────────┬─────────────────┬────────────────┘
    │                 │                 │
    │ IPC             │ IPC             │ IPC
    │                 │                 │
┌───▼──────────┐  ┌───▼──────────┐  ┌──▼──────────────┐
│  Renderer    │  │  Renderer    │  │  GPU Process    │
│  Process 1   │  │  Process 2   │  │                 │
│  (Tab 1)     │  │  (Tab 2)     │  │  • Compositing  │
│              │  │              │  │  • Rendering    │
│  • WebCore   │  │  • WebCore   │  │  • 3D Graphics  │
│  • JS Engine │  │  • JS Engine │  │                 │
└──────────────┘  └──────────────┘  └─────────────────┘

🔗 Integration Points

ZebraScript ↔ WebCore Integration

cpp

// source/webCore/src/dom/document.cpp
#include "zeprascript/runtime/vm.hpp"
#include "zeprascript/browser/window.hpp"

namespace WebCore {

class Document {
private:
    // JavaScript VM instance
    std::unique_ptr<Zepra::Runtime::VM> js_vm_;

public:
    void initializeJavaScript() {
        js_vm_ = Zepra::Runtime::VM::create();

        // Expose DOM to JavaScript
        auto* window = js_vm_->getGlobalObject();
        window->setProperty("document", this);
    }

    void executeScript(const std::string& code) {
        js_vm_->execute(code);
    }
};

} // namespace WebCore

WebCore ↔ Platform Integration

cpp

// source/platform/include/platform/window_system.hpp
namespace Platform {

class WindowSystem {
public:
    virtual void createWindow() = 0;
    virtual void destroyWindow() = 0;
    virtual void setTitle(const std::string& title) = 0;
    virtual void resize(int width, int height) = 0;
};

// Platform-specific implementations
#ifdef _WIN32
class WindowSystemWin : public WindowSystem { /* ... */ };
#elif defined(__linux__)
class WindowSystemLinux : public WindowSystem { /* ... */ };
#elif defined(__APPLE__)
class WindowSystemMacOS : public WindowSystem { /* ... */ };
#endif

} // namespace Platform

📊 Root CMakeLists.txt Integration

cmake

cmake_minimum_required(VERSION 3.20)
project(ZepraBrowser VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Options
option(ZEPRA_BUILD_TESTS "Build tests" ON)
option(ZEPRA_BUILD_DEVTOOLS "Build DevTools" ON)
option(ZEPRA_ENABLE_GPU "Enable GPU acceleration" ON)
option(ZEPRA_ENABLE_EXTENSIONS "Enable extension support" ON)

# Browser Components (in source/)
add_subdirectory(source/zepraScript)      # JavaScript Engine
add_subdirectory(source/webCore)          # Rendering Engine
add_subdirectory(source/webGpu)           # GPU Acceleration
add_subdirectory(source/zepraEngine)      # Browser Window/UI
add_subdirectory(source/networking)       # Network Stack
add_subdirectory(source/storage)          # Storage System
add_subdirectory(source/platform)         # Platform Layer
add_subdirectory(source/sandbox)          # Sandboxing
add_subdirectory(source/extensions)       # Extensions
add_subdirectory(source/media)            # Media Support
add_subdirectory(source/devtools)         # DevTools

# Legacy Components (in src/ and include/)
add_subdirectory(src/auth)
add_subdirectory(src/config)
add_subdirectory(src/search)

# Main Browser Application
add_executable(ZepraBrowser
    src/main.cpp
    src/core/zepra_core.cpp
    src/ui/window.cpp
    src/ui/tab_manager.cpp
    # ... other sources
)

target_link_libraries(ZepraBrowser
    PRIVATE
        zepra-script          # JavaScript Engine
        web-core              # Rendering Engine
        zepra-engine          # Browser Window
        networking            # HTTP/WebSocket
        storage               # LocalStorage/IndexedDB
        platform              # OS Integration
        sandbox               # Security
        extensions            # Extension System
        media                 # Audio/Video
        devtools              # Developer Tools
)

# Tests
if(ZEPRA_BUILD_TESTS)
    add_subdirectory(tests)
endif()

🔧 Build Instructions

Prerequisites

bash

# Ubuntu/Debian
sudo apt install cmake ninja-build libsdl2-dev libcurl4-openssl-dev \
    libjson-c-dev libssl-dev libsqlite3-dev

# macOS
brew install cmake ninja sdl2 curl openssl sqlite

Build Commands

bash

# Configure
cmake -B build -G Ninja \
    -DZEPRA_BUILD_TESTS=ON \
    -DZEPRA_ENABLE_GPU=ON

# Build
cmake --build build -j$(nproc)

# Run
./build/bin/ZepraBrowser

Component-Only Builds

bash

# Build only ZepraScript
cmake --build build --target zepra-script

# Build only Browser Window Demo
cmake --build build --target zepra-browser

📊 File Summary

Click on the component names below to view the detailed file tree, internal architecture, and API documentation for each subsystem.

Component / Documentation	Location	Files	Status
ZepraScript	`source/zepraScript/`	1392	✅ Complete
WebCore	`source/webCore/`	10	✅ Implemented
ZepraEngine	`source/zepraEngine/`	31	✅ Implemented
Browser Headers	`include/`	30	✅ Complete
Browser Sources	`src/`	25	✅ Complete
Tests	`test/zeprascript/`	72	✅ Complete
TOTAL		~1500	✅

🚀 Current Status

✅ Completed

ZepraScript JavaScript Engine (full implementation)
WebCore Rendering Engine (DOM, CSS, Layout)
Browser Window Demo (NXRENDER native X11/OpenGL)
DevTools Protocol (Chrome CDP)
Authentication System (Ketivee SSO)
Zepra Stack Libraries:
- NxBase - Buffer, string, memory utilities
- NxJSON - JSON parser/serializer
- NxHTTP - HTTP client (replaces libcurl)
- NxXML - XML/HTML parser
- NxCrypto - TLS/crypto abstraction
ZepraWebView Developer Tools:
- Console tab with real ZepraScript logs
- Network tab with request monitoring
- Security tab with CORS/TLS info
- ConsoleLog, NetworkMonitor, SecurityChecker modules

🔄 In Progress

GPU Acceleration (WebGPU + NxGfx)
NXRender widget integration
HTML content rendering in viewport
NXAudio browser integration

📋 Planned

Service Workers
WebRTC
PWA Support
Extensions System
WebAssembly execution

📝 Notes

DO NOT MODIFY source/zepraScript/ without careful consideration
Browser tests require ZepraScript to be built first
Use FILETREE.md for quick reference of all files
See docs/ for detailed API documentation
USE_ZEPRA_STACK=ON to build with custom libraries
USE_NXRENDER=ON for native X11/OpenGL rendering

Last Updated: 2025-12-14
Version: 1.1.0
Maintainer: Swanaya