# opnsense/core architecture

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

- Interactive diagram: https://gitdiagram.com/opnsense/core
- Repository: https://github.com/opnsense/core

## Overview

The project in question is the core of the OPNsense open source firewall and system management platform. Given its enormous file tree and the README details, it is clearly a full‐scale network security solution with a rich web GUI, back-end services, a build system, and a modular architecture based on the MVC pattern.

- Frontend (GUI/MVC) – The “src/opnsense/mvc” folder indicates the MVC structure with controllers, models, and views for the web GUI. The views, templates, and layout parts are clearly separated.
- Core System Services – The “src/opnsense/service” directory holds configuration daemons, service modules, and system scripts. This is where services like configuration management, logging (syslog), and template management reside.
- Backend Libraries & Framework – The “src/opnsense/mvc/app/library” area (with subfolders like Auth, Core, Firewall, Mvc, etc.) forms the backbone of business logic, authentication, firewall rules, interface management, and system utilities.
- Build and Deployment Tools – Files like the Makefile, various “Mk” files, and the “Scripts”, “contrib”, and “work” directories show a comprehensive build system used to compile, package, lint, and style-check the codebase.
- Test Suites – The “src/opnsense/mvc/tests” folder demonstrates unit and integration test structures to ensure code quality.
- External Dependencies and Contributions – The “contrib” directory contains third-party integrations or libraries (for example, parallel-lint, base32, etc.) that augment core functionality.
- Configuration and Templates – Within “src/opnsense/service/conf” and the “service/templates” directories are the configuration files and templates used by various subsystems (like Firewall, DHCP, VPN, etc.). These elements are critical in mapping how the system is configured and managed.

##### Relationships and interactions between the components
- The MVC layer (controllers, models, views) communicates with the core libraries to perform operations (e.g., authentication, firewall rule management) and later renders the GUI.
- The frontend sends requests (often via REST/HTTP APIs) to backend modules; for example, the “configd” service acting as the gateway for configuration changes.
- The build tools integrate with the source code (e.g. Makefile targets like “package”, “update”, “upgrade”, “lint”, “style”) ensuring efficient development and deployment workflows.
- System services (in “src/opnsense/service”) use configuration templates to modify system behavior and interact with the underlying operating system components (network interfaces, logging, security modules).
- The test suite acts as a safety layer by running checks across both MVC layers and underlying libraries.

##### Architectural patterns and design principles
- Use of MVC: The separation of the presentation layer, business logic, and data handling is clearly enforced.
- Modularity: Each major service (e.g., firewall, DHCP, VPN including IPsec, OpenVPN, Wireguard) is encapsulated as its own component with clearly defined APIs and configuration.
- Build pipeline integration: The repository includes extensive build, lint, and style tools which are integral to ensuring robust continuous integration and deployment.
- Extensibility: Directories like “contrib” and the template-based “service/templates” facilitate plugging in new features or modifying existing ones without reworking the core components.

##### Relevant technologies, frameworks, or libraries
- PHP (for the web GUI and MVC controllers/models).
- Python (for various scripts and helper tools across DHCP, firewall filtering, health monitoring, etc.).
- Shell scripting and Makefile-based build processes.
- FreeBSD system components and package management (the repository’s structure indicates alignment with FreeBSD build systems).
- Integration with third-party libraries like phpcs for style checks, and tools in “contrib” for various functionalities.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FE["Frontend (GUI/MVC)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        BL["Backend Libraries & Framework"]:::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        CS["Core System Services"]:::services
        CF["Configuration Files"]:::config
        CT["Templates"]:::config
    end

    %% Build & Test Layer
    subgraph "Build & Test"
        MF["Makefile"]:::build
        MK["Mk Files"]:::build
        SC["Scripts"]:::build
        WD["Work Directory"]:::build
        TS["Test Suites"]:::test
    end

    %% External Dependencies
    ED["External Dependencies & Contributions"]:::external

    %% Interactions
    FE -->|"calls"| BL
    BL -->|"invokes"| CS
    BL -->|"integrates"| ED
    CF -->|"provides"| CS
    CT -->|"supplies"| CS

    %% Build & Test flow
    MF -->|"triggers"| MK
    MK -->|"triggers"| SC
    SC -->|"triggers"| WD
    WD -->|"triggers"| TS

    TS ---|"CI/CD tests"| FE
    TS ---|"CI/CD tests"| BL
    TS ---|"CI/CD tests"| CS

    %% Classes and Colors
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef services fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef config fill:#ffffe0,stroke:#333,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef test fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef external fill:#e6e6fa,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/opnsense/core/tree/master/src/opnsense/mvc"
    click CS "https://github.com/opnsense/core/tree/master/src/opnsense/service"
    click BL "https://github.com/opnsense/core/tree/master/src/opnsense/mvc/app/library"
    click MF "https://github.com/opnsense/core/tree/master/Makefile"
    click MK "https://github.com/opnsense/core/tree/master/Mk"
    click SC "https://github.com/opnsense/core/tree/master/Scripts"
    click WD "https://github.com/opnsense/core/tree/master/work"
    click TS "https://github.com/opnsense/core/tree/master/src/opnsense/mvc/tests"
    click ED "https://github.com/opnsense/core/tree/master/contrib"
    click CF "https://github.com/opnsense/core/tree/master/src/opnsense/service/conf"
    click CT "https://github.com/opnsense/core/tree/master/src/opnsense/service/templates"
```
