# h-bf/sgroups architecture

> Architecture diagram of the GitHub repository h-bf/sgroups, 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/h-bf/sgroups
- Repository: https://github.com/h-bf/sgroups

## Overview

##### Project Overview
- This is a Go-based security groups service that appears to encompass several interlocking components. It handles security group configuration, network rules (including Terraform integration and nftables rule generation), and likely performs synchronization across different network elements.
- The project is organized as a multi-binary/microservice application. There are several command line binaries (found under the cmd/ directory) such as “sgroups-tf-v2”, “sgroups”, and “to-nft” that suggest distinct roles:
– “sgroups” likely runs the main security groups API/server.
– “sgroups-tf-v2” appears to be a Terraform provider integration.
– “to-nft” is likely involved in converting or applying rules to nftables.
- There is a clear separation between the core application (internal/app and internal/api packages), domain logic (internal/domains/sgroups), registries and persistence (internal/registry/sgroups with PostgreSQL migrations and in-memory registries), and auxiliary functions/agents (internal/app/agent).

##### Analysis of the File Structure (Key Components & Their Functions)
- Dockerfiles (Dockerfile.goose, Dockerfile.sgroups, Dockerfile.terraform, Dockerfile.to-nft): These indicate containerized deployments for different service components.
- Configuration Scripts (in the config/ directory): Used for install/uninstall, service configuration (systemd file for example) and rule flushing.
- Internal API (internal/api/sgroups): Contains the core API endpoints and related business logic for managing security groups.
- Application Logic:
- internal/app/agent: Implements the “agent” components that monitor network changes, handle DNS resolution, apply nftables changes, and execute jobs (like nft-applier-job).
- internal/app/sgroups-server: Likely handles requests coming into the security groups service, sets up HTTP/gRPC servers, configures logging, authentication, and database access (including PostgreSQL interactions).
- internal/app/sgroups-tf-provider: Provides integration with Terraform so that the security groups can be managed or provisioned via Terraform scripts. It defines fixtures, resource schema and provider configurations.
- Registry and Persistence:
- internal/registry/sgroups: Provides both in-memory and PostgreSQL database registries for storing rules, events, and sync actions.
- The PostgreSQL migrations (under internal/registry/sgroups/pg/migrations) signal that changes in the database schema are versioned.
- gRPC and Networking:
- internal/grpc: Implements client-provider logic and JSON codecs, likely used by internal services or for external integration.
- Documentation:
- The documentation directory is extensive and includes technical docs, API reference, and integration guides which inform how various parts interact.

a. Main Components:
- Sgroups API / Service: The central server (cmd/sgroups) that acts as the main entry point for security groups management.
- Sgroups Terraform Provider: (cmd/sgroups-tf-v2 and internal/app/sgroups-tf-provider) that enables integration with Terraform.
- NFTables Interface: (cmd/to-nft and internal/app/agent/nft) responsible for translating security group rules into nftable rules for firewall enforcement.
- Agent Subsystem: (internal/app/agent) handling asynchronous jobs, events from network interfaces, DNS resolution, health checks, telemetry, etc.
- Data Persistence & Registry: (internal/registry/sgroups) that coordinates both in-memory state and external PostgreSQL database storage.
- External Integration & gRPC: (internal/grpc) when external systems or microservices consume or send data.
- Supporting Components: Configuration scripts, Docker containers for deployment, and CI/CD infrastructure (GitHub workflows).

b. Relationships and Interactions:
- The Sgroups API receives incoming requests (e.g., via HTTP or gRPC) and interacts with the underlying registry components for CRUD operations on rules.
- The agent subsystem runs parallel jobs (nft-applier, DNS refresher, event processors) that update firewall configurations by communicating with the NFTables interface.
- The Terraform provider component interacts with external systems (i.e., cloud providers or configuration management tools) and then leverages internal API/registry modules to manage state.
- gRPC clients (or other API consumers) may call into both the primary sgroups service and possibly the agent for status updates.
- Database operations occur via the Sgroups server accessing PostgreSQL, with migrations ensuring schema integrity.
– API calls from external users to Sgroups API.
– Data flow between the API and database (through registry).
– The agent periodically pulling or pushing data to update nftables or perform synchronization.
– Terraform provider’s API calls to the Sgroups service.
– gRPC communications indicated where needed.

c. Architectural Patterns and Key Technologies:
- Microservice/Binary Separation: Different responsibilities are split across distinct cmd directories and their corresponding Docker containers.
- Clean Domain Separation: Domain logic resides in internal/domains, keeping business rules clearly separated.
- Dependency Injection & Observer Patterns: Found in internal/patterns, where observers and event handlers manage state changes.
- Containerization & CI/CD: Presence of Dockerfiles and comprehensive GitHub workflows indicate automated builds, testing, and deployment.
- Language & Libraries: Built in Go using standard libraries, with clear usage of Terraform’s provider model and nftables integration.

- For a full-stack-like application (though in this case it’s more of a backend service), focus on:
– The separation between command-line service binaries and their responsibilities.
– Integration points with external systems (e.g., Terraform, database, and nftables).
– Label components clearly (for example: “Sgroups API Service”, “Terraform Provider”, “NFTables Agent”, “Postgres Database”, “gRPC Module”).
- External requests → Sgroups API
- Sgroups API ↔ Registry/Database
- Agent → NFTables Module
- Terraform Provider ↔ Sgroups API and Domain Layer
- gRPC communications between clients and the respective server components.
– Service/binary components (rectangles for services)
– Integration layers (hexagons for external integrations like Terraform or nftables)

– Sgroups API/Server, Agent Subsystem, Terraform Provider, NFT Interface, Registry & Database, External Clients.
- Labels that denote the technologies and protocols (e.g., “HTTP API”, “gRPC”, “Database Access PostgreSQL”).
- Notes on configuration management (Docker containers, CI/CD pipelines as part of deployment) as side components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph for Service Binaries
    subgraph "Service Binaries"
        API["Sgroups API Service"]:::service
        TF["Terraform Provider"]:::integration
        AGENT["Agent Subsystem"]:::agent
        NFT["NFTables Interface"]:::integration
    end

    %% Subgraph for Data & Integration Layer
    subgraph "Data & Integration Layer"
        CLIENTS["External Clients"]:::external
        REG["Data Persistence & Registry"]:::database
        DB["Postgres Database"]:::database
        GRPC["gRPC Module"]:::external
    end

    %% Relationships
    CLIENTS -->|"HTTP_API"| API
    TF -->|"TerraformSync"| API
    API -->|"DBAccess"| REG
    REG -->|"Migrations"| DB
    API <-->|"grpc_calls"| GRPC
    AGENT -->|"nft_updates"| NFT
    AGENT -->|"StatusUpdates"| API

    %% Click Events for Component Mapping
    click API "https://github.com/h-bf/sgroups/tree/master/cmd/sgroups"
    click API "https://github.com/h-bf/sgroups/tree/master/internal/app/sgroups-server"
    click TF "https://github.com/h-bf/sgroups/tree/master/cmd/sgroups-tf-v2"
    click TF "https://github.com/h-bf/sgroups/tree/master/internal/app/sgroups-tf-provider"
    click NFT "https://github.com/h-bf/sgroups/tree/master/cmd/to-nft"
    click NFT "https://github.com/h-bf/sgroups/tree/master/internal/app/agent/nft"
    click AGENT "https://github.com/h-bf/sgroups/tree/master/internal/app/agent"
    click REG "https://github.com/h-bf/sgroups/tree/master/internal/registry/sgroups"
    click REG "https://github.com/h-bf/sgroups/tree/master/internal/registry/sgroups/pg/migrations"
    click GRPC "https://github.com/h-bf/sgroups/tree/master/internal/grpc"

    %% Styles
    classDef service fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef integration fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef agent fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef database fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
