# floorp-projects/floorp-12 architecture

> Architecture diagram of the GitHub repository floorp-projects/floorp-12, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/floorp-projects/floorp-12
- Repository: https://github.com/floorp-projects/floorp-12

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Applications Layer
    subgraph "UI Applications Layer"
        UA1["UI: Main Browser"]:::ui
        UA2["UI: New Tab"]:::ui
        UA3["UI: Notes"]:::ui
        UA4["UI: Settings"]:::ui
        UA5["UI: Startup"]:::ui
        UA6["UI: Welcome"]:::ui
    end

    %% Modules and Services Layer
    subgraph "Modules and Services Layer"
        MA["Modules & Actors System"]:::modules
        SS["Shared Packages & Utilities"]:::shared
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        CE1["Gecko/Branding (Engine)"]:::engine
        CE2["Rust: Nora-Inject"]:::engine
    end

    %% Build and Workflow Toolchain
    subgraph "Build and Workflow Toolchain"
        BT["Build & Config (build.ts, deno.json, Cargo.toml)"]:::build
        SC["Development Scripts"]:::build
    end

    %% Connections: UI Applications trigger Modules & use Shared Services
    UA1 -->|"triggers"| MA
    UA2 -->|"triggers"| MA
    UA3 -->|"triggers"| MA
    UA4 -->|"triggers"| MA
    UA5 -->|"triggers"| MA
    UA6 -->|"triggers"| MA

    UA1 -->|"uses"| SS
    UA2 -->|"uses"| SS
    UA3 -->|"uses"| SS
    UA4 -->|"uses"| SS
    UA5 -->|"uses"| SS
    UA6 -->|"uses"| SS

    %% Modules command Core Engine
    MA -->|"commands"| CE1
    MA -->|"commands"| CE2

    %% Shared Services support Core Engine
    SS -->|"supports"| CE1
    SS -->|"supports"| CE2

    %% Build Tools influence layers
    BT ---|"builds"| UA1
    BT ---|"builds"| MA
    BT ---|"builds"| CE1
    SC ---|"scripts"| UA1
    SC ---|"scripts"| MA
    SC ---|"scripts"| CE1

    %% Click Events
    click CE1 "https://github.com/floorp-projects/floorp-12/tree/main/gecko"
    click CE2 "https://github.com/floorp-projects/floorp-12/tree/main/crates/nora-inject"
    click UA1 "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/main"
    click UA2 "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/newtab"
    click UA3 "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/notes"
    click UA4 "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/settings"
    click UA5 "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/startup"
    click UA6 "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/welcome"
    click MA "https://github.com/floorp-projects/floorp-12/tree/main/src/apps/modules"
    click SS "https://github.com/floorp-projects/floorp-12/tree/main/src/packages"
    click BT "https://github.com/floorp-projects/floorp-12/blob/main/build.ts"
    click SC "https://github.com/floorp-projects/floorp-12/tree/main/scripts"

    %% Styling
    classDef ui fill:#CDEBFF,stroke:#0277BD,stroke-width:2px;
    classDef modules fill:#FFC8C8,stroke:#B71C1C,stroke-width:2px;
    classDef shared fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef engine fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
