# foobaroy/foomuuri architecture

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

- Interactive diagram: https://gitdiagram.com/foobaroy/foomuuri
- Repository: https://github.com/foobaroy/foomuuri

## Overview

##### Project Overview and Purpose
- Foomuuri is a firewall tool that leverages nftables to provide bidirectional (incoming, outgoing, and forwarding) firewall functionality.
- It supports advanced features such as zone-based filtering, macros, templates in its rule language, logging, rate limiting, dynamic IP list updates, geolocation, and multi-ISP monitoring.
- The project also includes integration points for systemd (via various service and timer unit configurations) and firewalld (for systems using NetworkManager’s zone support).

##### Analyzing the File Structure
- Core Sources: The firewall’s main logic is in the src/foomuuri folder. This is where the firewall engine – including parsing of the firewall rule language and interfacing with nftables – would reside.
- Configuration Files: The etc directory holds default and static configuration files (like “50-foomuuri.conf”) that likely determine runtime behavior.
- Integration with External Systems:
- The systemd directory contains service definitions (e.g., fi.foobar.Foomuuri1.conf, foomuuri.service, timers, etc.) used for service management and scheduled tasks.
- The firewalld directory has configuration files integrating with FirewallD, providing support for NetworkManager’s zone-based configurations.
- Documentation & Tests:
- The doc folder includes manuals, example scripts, and command-line examples.
- The test directory holds multiple configuration examples (organized by scenario such as “host”, “router”, “multi-isp”, etc.) along with “golden” output files for automated testing.

##### Guiding Principles
- Main components and their relationships:
a. Core Firewall Engine – Represented by the code in src/foomuuri. This is where firewall logic, rule parsing, and translation to nftables commands happens.
b. Configuration Management – Capturing both the static configuration files (in etc) and the dynamic rule language (macros/templates).
c. Integration Layers:
- systemd Integration – Represent service units and timers that start, monitor, and schedule firewall tasks.
- firewalld Integration – Represent the connection to FirewallD and its configuration for seamless integration with systems using NetworkManager.
d. API & External Interfaces – Highlight the D-Bus API provided by Foomuuri, which may interact with external programmatic clients.
e. Testing Suite – The test directory helps validate various firewall configurations and shows how multiple zones or special network scenarios are handled.

- Relationships and Interactions:
- From the engine, show output flows directed to nftables – indicating that rule synthesis is pushed to the underlying firewall system.
- A bidirectional link for the D-Bus API indicating both command input and event/notification output.
- Optionally, show test cases as validation flows, ensuring that the engine’s behavior under different configurations (each test scenario) results in defined “golden” outputs.

- Architectural Patterns and Technologies:
- Emphasis on modularity: separation between the rule parsing component, configuration loader, and firewall rule deployment.
- That the design leverages system integration patterns via systemd and firewalld.
- That integration with nftables leverages modern Linux kernel features, making the design “modern” and compatible with both IPv4 and IPv6.

##### Final Recommendations
- Since Foomuuri has both configuration complexity (with multiple test cases showing various network scenarios) and system integration complexities (systemd, firewalld, D-Bus, nftables), ensure that every component’s interaction is visualized.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Configuration & Resources"
        CM["Configuration Management"]:::config
        DOC["Documentation"]:::documentation
    end

    subgraph "Core Processing"
        CFE["Core Firewall Engine"]:::engine
        NFT["nftables Interface"]:::engine
    end

    subgraph "Integration Components"
        SYS["Systemd Integration"]:::integration
        FW_D["FirewallD Integration"]:::integration
        DBUS["D-Bus API"]:::integration
    end

    TS["Testing Suite"]:::testing

    CM -->|"loads"| CFE
    CFE -->|"executes"| NFT
    SYS -->|"triggers"| CFE
    FW_D -->|"triggers"| CFE
    CFE <-->|"notify"| DBUS
    TS <-->|"validate"| CFE

    click CFE "https://github.com/foobaroy/foomuuri/tree/main/src/foomuuri"
    click CM "https://github.com/foobaroy/foomuuri/tree/main/etc"
    click SYS "https://github.com/foobaroy/foomuuri/tree/main/systemd"
    click FW_D "https://github.com/foobaroy/foomuuri/tree/main/firewalld"
    click DOC "https://github.com/foobaroy/foomuuri/tree/main/doc"
    click TS "https://github.com/foobaroy/foomuuri/tree/main/test"

    classDef config fill:#9fdf9f,stroke:#000,stroke-width:1px;
    classDef documentation fill:#d3d3f8,stroke:#000,stroke-width:1px;
    classDef engine fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef integration fill:#f08080,stroke:#000,stroke-width:1px;
    classDef testing fill:#f4a460,stroke:#000,stroke-width:1px;
```
