# assetnote/surf architecture

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

- Interactive diagram: https://gitdiagram.com/assetnote/surf
- Repository: https://github.com/assetnote/surf

## Overview

##### Main Components
- CLI Application (cmd/surf): This is the entry-point executable code. It parses user input (flags, file arguments), triggers scanning, and coordinates output.
- Core Library / Modules (pkg/surf): This package encapsulates the logic for sending HTTP requests (using httpx), processing responses, filtering hosts (including functions in files like httpx.go, process.go, safeseenhosts.go, surf.go, and utils.go).
- External Dependency – HTTPx: Mention the integration with the external “httpx” library which performs HTTP probing.
- Output Manager: The component (or logic within pkg/surf) that writes results to timestamped files (external-{timestamp}.txt and internal-{timestamp}.txt).
- GitHub Actions / Deployment: The .github/workflows and goreleaser configuration files indicate continuous integration/deployment processes for release management.

##### Relationships and Interactions
- The CLI (cmd/surf) invokes functions in the pkg/surf package.
- Within pkg/surf, HTTP requests are sent using the httpx library – this is a critical dependency for probing the given hosts.
- The scanning process typically takes a list of hosts provided via command-line flags and processes them through the core logic, which categorizes each host based on response or timeout.
- Once processed, the results are both printed to stdout and saved into output files.
- Additional pipeline elements include error capturing and basic analysis applied on httpx responses before printing or saving results.
- CI/CD pipelines (via GitHub workflows) automatically manage testing/building/deployment/release processes when changes are pushed.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The architecture distinguishes between user interaction (CLI) and core business logic (pkg/surf). This modular structure simplifies maintenance and testing.
- Extensibility: The clear separation between command-line argument parsing, request processing, and output generation allows for easier future extensions or integration points.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Scanning Process
    subgraph "Scanning Process"
        CLI["CLI Interface (cmd/surf)\nParses input, manages concurrency and timeout"]:::blue
        CORE["Core Processing Module (pkg/surf)\nOrchestrates HTTP probing and response processing"]:::blue
        HTTP["HTTP Probing Service (httpx)\nSends HTTP requests and captures responses"]:::green
        OUTPUT["Output Manager\nPrints to stdout and writes timestamped files"]:::blue

        CLI -->|"invokes"| CORE
        CORE -->|"sendsHTTPrequest"| HTTP
        HTTP -->|"returnsResponses"| CORE
        CORE -->|"outputsResults"| OUTPUT
    end

    %% CI/CD Deployment Pipeline
    subgraph "Deployment & CI/CD"
        WORKFLOW["GitHub Actions Workflow\nAutomates builds, tests, and releases"]:::orange
        GORELEASER["Goreleaser Config\nManages release packaging"]:::orange
    end

    %% Triggering automation (repository commit simulation)
    REPO["Source Code Update\n(Commit triggers CI/CD)"]:::blue
    REPO -->|"triggers"| WORKFLOW
    REPO -->|"triggers"| GORELEASER

    %% Click Events
    click CLI "https://github.com/assetnote/surf/blob/master/cmd/surf/main.go"
    click CORE "https://github.com/assetnote/surf/tree/master/pkg/surf/"
    click HTTP "https://github.com/assetnote/surf/blob/master/pkg/surf/httpx.go"
    click OUTPUT "https://github.com/assetnote/surf/blob/master/pkg/surf/surf.go"
    click WORKFLOW "https://github.com/assetnote/surf/blob/master/.github/workflows/release.yml"
    click GORELEASER "https://github.com/assetnote/surf/blob/master/.goreleaser.yml"

    %% Styles
    classDef blue fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef green fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef orange fill:#FFD580,stroke:#000,stroke-width:2px;
```
