How floorp-projects/floorp-12 works
Project Type and Purpose
• Floorp Browser is a cross-platform web browser built on Firefox’s engine.
• Its goal is to keep the open, private, and sustainable web alive.
• The README and file tree show that it supports customization (e.g., different branding like “floorp-official,” “floorp-daylight,” and “noraneko-unofficial”), along with components for UI (new tab, settings, welcome, notes, etc.) and core functionality (gecko integration, modules, injection libraries in Rust, etc.).
• It uses technologies such as Rust (via Cargo and crates), TypeScript/JavaScript (many src/apps and packages directories), and Deno for development tasks.
File Structure – Key Directories and Components
• At the root you have configuration files (.gitignore, Cargo.toml, build.ts, deno.json, etc.) that set up the build and development environment.
• The “gecko” directory contains the branded themes and other Firefox-specific modifications. This likely represents the underlying browser engine instance and any integration work with Firefox code.
• The “crates” folder (e.g., nora-inject) contains Rust code used for injection or transformation tasks, indicating an interplay between native code (Rust) and higher-level browser components.
• The “src” folder holds multiple “apps” directories – each representing a separate UI application or module:
• “src/apps/main” is the central browser application (core UI and functionality).
• Other apps include “newtab”, “notes”, “settings”, “welcome”, “startup”, etc. Each has its own assets, components, style files, and configuration (often using TypeScript/React-like components).
• The “src/apps/modules” folder holds modules (likely pluggable components or actors) that may interact with browser internals like tab management, settings, or UI elements.
• The “src/packages” directory includes shared libraries and utilities (e.g., user-js-runner, custom-shortcut-key, skin packages, and even integration with testing frameworks like vitest). This shows the project’s commitment to modularity and reuse.
• The “scripts” directory includes various development and build scripts, handling tasks like hot reload (HMR) with Deno, Git patches management, CSS updates, and injection related utilities.
• The .github folder and related configuration files indicate CI/CD pipeline configurations, automated testing and build workflows (with assets for different OS platforms).
Core Components and Their Interactions
• Browser Engine & Core
• “gecko” folder along with its configuration and branding as the underlying engine and platform integration layer.
• Integration points from the Rust-based modules (from “crates/nora-inject”) that possibly alter or extend browser behavior.
• UI Applications
• Major application (e.g., main browser UI, new tab, settings, welcome, notes, startup) as individual modules. Show that these separate “apps” share a common development stack (TypeScript/React-like components, CSS design, Deno tasks for hot reload).
• Modules and Actors System
• The “src/apps/modules” directory should be illustrated as the layer that coordinates background operations such as managing profiles, tabs, search engines, and other browser-specific actors.
• How these actors communicate between the UI and the underlying engine (e.g., NRTabManager, NRSettings, NRChromeModal).
• Shared Services and Packages
• Various “src/packages” components that offer shared logic (e.g., UI skins, custom shortcut functionalities, solid-xul for UI elements, user-js integration).
• Modular design and that these packages can be plugged into or updated separately.
• Build and Workflow Toolchain
• A separate block representing the development workflow: the Deno tasks (shown in “scripts” and in the README instructions) handle hot reload, build tasks, and integration with GitHub Actions as shown via the workflows directory.
• Configuration files (like “Cargo.toml”, “deno.json”, “vite.config.ts”) are used to build and run the various languages and platforms (Rust, Deno/TypeScript, etc.).
Architectural Patterns and Design Principles
• Modular Architecture: The separation into apps, modules, packages, and scripts emphasizes a modular, loosely-coupled system.
• Multi-Layered Structure:
• Core Engine/Branding Layer (gecko and native Rust code) at the bottom.
• Middleware or Services Layer (modules and shared packages) in the middle.
• Presentation Layer (UI apps like main browser, new tab, settings, welcome, etc.) on top.
• Clear separation of concerns and the use of dependency injection and inter-component messaging (as can be inferred from the “actors” naming and RPC modules in the lib directories).
• Cross-platform Compatibility is supported with OS-specific build and branding assets (illustrated under gecko/branding, .github/workflows assets, and installation instructions in the README).