Orivon Browser

A Web3-centric, trustless, user-friendly desktop browser

This repository contains the first fullstack foundation milestone for Orivon Browser—a modern desktop application built with Electron and React that serves as a bridge between users and Web3 applications.

🎯 Project Scope

This milestone focuses on building the browser shell, dashboard, permissions system, and foundational architecture needed to support future runtime integration. It is not focused on building the native browser runtime or implementing actual web rendering.

What's Included

• ✅ Browser shell with tab management
• ✅ URL bar and navigation controls
• ✅ Dashboard/new tab page with app grid
• ✅ Permissions and safety UI framework
• ✅ Mock adapter layer for clean runtime integration
• ✅ TypeScript contracts for all major entities
• ✅ Zustand + Context state management
• ✅ Dark/light theme support
• ✅ Unit tests and CI/CD pipeline

What's NOT Included (Next Phases)

• ⏱️ Rust/C++ runtime engine
• ⏱️ WebView integration for actual web content
• ⏱️ Real blockchain interaction
• ⏱️ Desktop app distribution

🏗️ Architecture

High-Level Structure

src/
├── main/                    # Electron main process
│   ├── index.ts            # App lifecycle, IPC handlers
│   └── preload.ts          # Sandboxed IPC bridge
├── renderer/               # React application
│   ├── App.tsx             # Root component with routing
│   ├── pages/              # Page components (Dashboard, BrowserWindow)
│   ├── components/         # Reusable UI components
│   ├── store/              # Zustand state stores
│   ├── context/            # React Context providers
│   ├── styles/             # Global and component CSS
│   └── index.tsx           # React root
└── lib/
    ├── contracts/types.ts  # TypeScript contracts (shared types)
    └── adapters/           # Mock implementations (swappable with IPC)

Key Design Principles

1. Clean Adapter Layer: All runtime-dependent code uses adapters that can be swapped from mock to IPC-based implementations without changing components
2. TypeScript Contracts First: All entity shapes (apps, permissions, modules) defined as contracts upfront
3. State Management: Zustand for complex state (apps, permissions, navigation), React Context for UI state (modals, toasts)
4. Minimal Security Hardening: Preload script exposes only safe IPC methods; no direct fs or require access
5. Future-Ready: Code structured to integrate cleanly with Rust/C++ runtime via IPC

Contract System

Key contracts defined in src/lib/contracts/types.ts:

• AppManifest — Application metadata, permissions, trust score
• Permission — Permission shape with risk level
• PermissionGrant — User-granted permissions for an app
• TrustScore — Trust level (Verified/Known/Unknown/Risky) + score (0-100)
• NavigationState — Browser tabs, active tab, history
• UserSettings — Theme, homepage, experimental features
• IPCMessageType — Enum of all IPC message types (extensible for future)

🚀 Getting Started

Prerequisites

• Node.js 18+ or 20+
• npm 9+

Installation

# Clone the repository
git clone https://github.com/OrivonBrowser/orivon-browser.git
cd orivon-browser

# Install dependencies
npm install

Development

# Start dev server (hot reload enabled)
npm run dev

# This runs:
# - Electron main process with file watching
# - Vite dev server for React renderer (localhost:5173)

# In a separate terminal, you can also run individual processes:
npm run dev:main      # Electron main process only
npm run dev:renderer  # Vite dev server only

Building

# Build for production
npm run build

# Build + package into distributable (Windows installer + portable exe)
npm run build:dist

Testing

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Code Quality

# Type-check (TypeScript)
npm run type-check

# Lint code (ESLint)
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code (Prettier)
npm run format

# Validate all (lint + type-check + test)
npm run validate

📁 Project Structure

/src/main — Electron Main Process

• index.ts — App lifecycle (create window, handle close), IPC handlers for mock data
• preload.ts — Sandboxed preload script; exposes safe IPC APIs to renderer

/src/renderer — React Application

Pages:

• Dashboard.tsx — Welcome page with app grid and shortcuts
• BrowserWindow.tsx — Browser content area (placeholder for now)

Components:

• Layout.tsx — Main layout wrapper with header
• TabBar.tsx — Tab management (add, close, switch)
• UrlBar.tsx — URL input and search
• NavControls.tsx — Back, forward, reload, home buttons
• TrustBadge.tsx — Visual trust indicator
• SettingsModal.tsx — Settings UI
• PermissionRequest.tsx — Permission grant/deny dialog

State Management:

• store/appsStore.ts — Zustand store for installed/available apps
• store/permissionsStore.ts — Permission requests and grants
• store/navigationStore.ts — Browser tabs and navigation state
• store/settingsStore.ts — User preferences
• context/UiContext.tsx — React Context for UI state (modals, toasts)

/src/lib — Shared Libraries

Contracts:

• contracts/types.ts — All TypeScript interfaces and types

Adapters:

• adapters/types.ts — Adapter interfaces (for DI pattern)
• adapters/appsAdapter.ts — Mock app list implementation
• adapters/permissionsAdapter.ts — Mock permission handling
• adapters/settingsAdapter.ts — Mock settings storage
• adapters/trustAdapter.ts — Mock trust scores
• adapters/index.ts — Adapter factory & DI container

🔌 Adapter System (Future Runtime Integration)

The adapter layer abstracts all runtime-dependent code. Current implementations are mock, but can be swapped for IPC-based calls:

// Current: Mock adapter
const apps = await appsAdapter.getInstalledApps();

// Future: Will swap to IPC-based implementation
// const apps = await window.api.getInstalledApps();
// No component changes needed!

To integrate the real Rust/C++ runtime:

1. Update src/lib/adapters/index.ts to conditionally return IPC-based implementations
2. Define matching IPC handlers in src/main/preload.ts
3. Implement matching handlers in the Rust runtime
4. Components remain unchanged

🎨 Styling

• No framework dependencies — Pure CSS modules for fast builds
• Dark/light theme — Toggled via .dark class on <html>
• Responsive — Grid-based layouts for scalability
• Minimal — Focused on clean, professional appearance

🧪 Testing

Testing setup uses Vitest + React Testing Library:

npm run test          # Run all tests
npm run test:coverage # Generate coverage report

Current test suite includes:

• Adapter tests (mock data validation)
• Contract tests (type validation)
• Component tests (UI rendering)

Aim: 60%+ coverage for MVP; expand in future phases.

🔐 Security Considerations

Electron Hardening

• ✅ Context isolation enabled
• ✅ Sandbox mode enabled
• ✅ Node integration disabled
• ✅ Preload script sandboxed
• ✅ No eval() or Function()

Preload Script

• Exposes only safe IPC methods
• No direct file system access
• No direct require() capability
• All calls validated on main process

Future: WebView Sandbox

When integrating real WebView:

• Use <webview> tag with sandbox attribute
• IPC for communication between webview and main process
• Restrict capabilities per app

🚦 CI/CD Pipeline

GitHub Actions workflow (.github/workflows/ci.yml):

• Triggers: Push to main/develop, PRs
• Node.js versions: 18.x, 20.x
• Steps:
  1. Install dependencies
  2. Type-check (TypeScript)
  3. Lint (ESLint)
  4. Run tests (Vitest)
  5. Build (Vite + main bundle)
  6. Upload artifacts

All checks must pass before merge.

📝 Contributing

See CONTRIBUTING.md for guidelines on:

• Branch naming and commit messages
• Testing requirements
• Code style and formatting
• Pull request process

🗺️ Roadmap

Phase 1 (Current) ✅

• Browser shell and dashboard
• Permissions UI framework
• Mock data and adapters
• Type contracts

Phase 2

• Rust/C++ runtime engine
• Real app loading and sandbox
• Actual permission system
• Trust score API integration

Phase 3

• WebView integration
• Real web content rendering
• Network requests & data privacy
• Advanced security features

Phase 4+

• App store and distribution
• User profiles and sync
• Advanced analytics
• Browser extensions support

📚 Documentation

• Implementation Specs — Full design specifications
• Architecture Notes — Inline comments for contracts
• Adapter System — How to add new adapters

💡 Key Decisions

Single-Package Structure (Not Monorepo)

Why: Simpler setup and iteration for MVP; can split into monorepo later if needed.

Zustand + Context Hybrid

Why:

• Zustand for complex app state (performant, minimal boilerplate)
• Context for UI state (no extra library, simpler for local state)

Mock Adapters from Day 1

Why: Clean integration path for runtime; ensures contracts are validated early.

Full CI from Day 1

Why: Catches issues early; maintains code quality as team scales.

🤝 Support

For questions or issues:

• Open an issue on GitHub
• Join Discord (technical-chat)
• Read implementation specs: https://docs.orivonstack.com/

📄 License

Apache-2.0 — See LICENSE for details

---

Ready to contribute? Start with CONTRIBUTING.md and check out the implementation specs.

Want to run the app right now?

npm install
npm run dev

That's it! 🚀