# lasseh/whynoipv6 architecture

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

- Interactive diagram: https://gitdiagram.com/lasseh/whynoipv6
- Repository: https://github.com/lasseh/whynoipv6

## Overview

##### Project Type and Purpose
- This repository is one part of a three-repo ecosystem (backend, frontend, and campaigns) for a service called “WhyNoIPv6,” which tracks and “shames” high-traffic websites for not adopting IPv6.
- Its key functions include scanning domains (using a crawler), aggregating IPv6-related metrics (e.g., DNS and MX record checks), and providing an API for retrieval of this data. There’s also a command-line tool repository (cmd/v6manage) for managing campaigns and related operations.

##### Analyzing the File Structure
- Two main command directories exist under "cmd":
- cmd/api – holds the main API server (main.go) that likely handles REST requests.
- cmd/v6manage – collections of subcommands (e.g., campaign, crawl, import) for managing domain campaigns and utilities.
- The “internal” directory subdivides into components such as:
- config – configuration handling.
- core – contains business logic for domain, campaign, changelog, metrics, country, and more.
- geoip – for GeoIP functionality, supplemented by the “db/geoip” containing GeoLite2 DB files.
- logger – logging functionality.
- postgres – database-related code and generated SQL queries, including models and integration layer.
- resolver – likely handling domain name resolution tasks.
- rest – API endpoint handlers (campaign, changelog, error handler, etc.).
- toolbox – secondary features like healthchecks and notifications.
- Database migration and query definitions are in the “db” directory.
- Extra directories include deployment resources such as systemd service files, nginx configs, and Grafana dashboards.
- Build/deployment scripts (Makefile, .golangci.yml, go.mod) denote that the project is built and deployed via standard tooling.

##### Main Components
a. Web API Server (cmd/api):
- Represented as the layer that interfaces with clients using REST endpoints from “internal/rest.”
- It interacts with business logic in “internal/core,” calls on “internal/geoip” and “internal/resolver” as needed, and logs via “internal/logger.”

b. Crawler and Utility Application (cmd/v6manage):
- Handles operational tasks such as domain crawling, campaign imports, campaign listings, changelog generation, etc.
- Acts as the driver for periodic scanning of domains (every 3 days, as per README) and management of campaign data.

c. Database Layer:
- Consists of both physical database assets (migrations in “db/migrations” and actual SQL queries in “db/query”) and the PostgreSQL integration (in “internal/postgres”).
- This component is responsible for storing domain scan results, metrics, and other campaign data.

d. GeoIP Module:
- Incorporate the GeoIP functionalities that use the GeoLite2 databases. It is represented in both the “db/geoip” (data files) and “internal/geoip” (logic).

e. Configuration and Logging Utilities:
- These include “internal/config” for managing configuration settings and “internal/logger” for logging, which cut across the entire system.

f. Deployment/Infrastructure:
- External service configurations are provided via files in the “extra” directory (nginx configurations, systemd service definitions, logrotate, etc.).
- They indicate how the application is deployed and monitored in production.

##### Relationships and Interactions
- The API layer receives HTTP requests and forwards them to REST handler functions within “internal/rest,” which invoke business logic in “internal/core.”
- The business logic further interacts with the data layer (Postgres operations via “internal/postgres”) and possibly leverages utility functions (healthchecks, notifications) from “internal/toolbox.”
- The crawler tool (cmd/v6manage) operates offline or as scheduled jobs, updating the campaigns and domain scan data in the database.
- External modules such as the GeoIP processor use the provided database files in “db/geoip” along with application logic in “internal/geoip” to resolve additional domain information.
- A resolver component is responsible for handling DNS querying, such as checking DNS and MX records.
- Deployment components (systemd, nginx) tie the API and crawler applications to their hosting environment, ensuring they are properly managed and exposed.

##### Architectural Patterns & Design Principles
- The project follows a modular monolith with clearly separated concerns: each subdirectory encapsulates a discrete functionality (e.g., core business logic, REST endpoints, database access).
- It follows a layered architecture: the API layer sits atop the business logic/core, which in turn communicates with the database and external services (like DNS, GeoIP).
- Command structure for separate CLI tools (via cmd/api and cmd/v6manage) shows an intent to decouple the management utilities from the API service.
- The separation between deployment (extra) and application logic highlights a design that is deployment-agnostic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        API_Server["API Server (cmd/api)"]:::apiLayer
        V6Manage_CLI["V6Manage CLI (cmd/v6manage)"]:::cli
        Scheduler["Scheduler (runs every 3 days)"]:::cli
    end

    %% Internal Components
    subgraph "Internal Components"
        REST_Handlers["REST Handlers (internal/rest)"]:::rest
        Business_Logic["Business Logic (internal/core)"]:::logic
        Postgres_Integration["Postgres Integration (internal/postgres)"]:::db
        GeoIP_Logic["GeoIP Logic (internal/geoip)"]:::geoip
        Resolver["Resolver (internal/resolver)"]:::logic
        Toolbox["Toolbox (internal/toolbox)"]:::logic
    end

    %% Utilities
    subgraph "Utilities"
        Config["Configuration (internal/config)"]:::util
        Logger["Logging (internal/logger)"]:::util
    end

    %% Database Layer
    subgraph "Database Layer"
        Postgres_DB["PostgreSQL DB"]:::db
        Migrations["Migrations (db/migrations)"]:::db
        Queries["Queries (db/query)"]:::db
    end

    %% GeoIP Data
    subgraph "GeoIP Data"
        GeoLite2["GeoLite2 DB Files (db/geoip)"]:::geoip
    end

    %% Deployment / Infrastructure
    subgraph "Deployment/Infrastructure"
        Nginx["Nginx Config (extra/nginx)"]:::infra
        Systemd["Systemd Service (extra/systemd)"]:::infra
        Logrotate["Logrotate (extra/logrotate)"]:::infra
        Grafana["Grafana Dashboard (extra/grafana_dashboard.json)"]:::infra
    end

    %% Connections for Application Flow
    API_Server -->|"HTTPRequest"| REST_Handlers
    REST_Handlers -->|"Calls"| Business_Logic
    Business_Logic -->|"DBOps"| Postgres_Integration
    Business_Logic -->|"GeoIPLookup"| GeoIP_Logic
    Business_Logic -->|"DNSQuery"| Resolver
    Business_Logic -->|"UtilCall"| Toolbox
    API_Server -->|"Uses"| Config
    API_Server -->|"Logs"| Logger
    V6Manage_CLI -->|"UpdatesDB"| Postgres_DB
    V6Manage_CLI -->|"ManagesCampaigns"| REST_Handlers
    Scheduler --> V6Manage_CLI

    %% Internal to Database Layer
    Postgres_Integration -->|"Executes"| Postgres_DB
    Migrations -->|"Migrates"| Postgres_DB
    Queries -->|"Queries"| Postgres_DB

    %% GeoIP Module Connection
    GeoIP_Logic -->|"UsesData"| GeoLite2

    %% Deployment Connections
    Nginx -->|"RoutesTo"| API_Server
    Systemd -->|"Manages"| API_Server
    Systemd -->|"Manages"| V6Manage_CLI
    Logrotate -->|"ManagesLogs"| Logger
    Grafana -->|"Monitors"| API_Server

    %% Click Events for Component Mapping
    click API_Server "https://github.com/lasseh/whynoipv6/blob/master/cmd/api/main.go"
    click REST_Handlers "https://github.com/lasseh/whynoipv6/blob/master/internal/rest/server.go"
    click V6Manage_CLI "https://github.com/lasseh/whynoipv6/blob/master/cmd/v6manage/main.go"
    click V6Manage_CLI "https://github.com/lasseh/whynoipv6/blob/master/cmd/v6manage/cmd/campaign.go"
    click Postgres_Integration "https://github.com/lasseh/whynoipv6/blob/master/internal/postgres/postgres.go"
    click Postgres_DB "https://github.com/lasseh/whynoipv6/tree/master/db"
    click GeoIP_Logic "https://github.com/lasseh/whynoipv6/blob/master/internal/geoip/geoip.go"
    click GeoLite2 "https://github.com/lasseh/whynoipv6/blob/master/db/geoip/GeoLite2-ASN.mmdb"
    click Config "https://github.com/lasseh/whynoipv6/blob/master/internal/config/config.go"
    click Logger "https://github.com/lasseh/whynoipv6/blob/master/internal/logger/logger.go"
    click Nginx "https://github.com/lasseh/whynoipv6/tree/master/extra/nginx"
    click Systemd "https://github.com/lasseh/whynoipv6/tree/master/extra/systemd"
    click Logrotate "https://github.com/lasseh/whynoipv6/tree/master/extra/logrotate"
    click Grafana "https://github.com/lasseh/whynoipv6/blob/master/extra/grafana_dashboard.json"

    %% Styles
    classDef apiLayer fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef cli fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef rest fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef db fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef geoip fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef util fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef infra fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
