# pardim93/http_to_https architecture

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

- Interactive diagram: https://gitdiagram.com/pardim93/http_to_https
- Repository: https://github.com/pardim93/http_to_https

## Overview

1. **Repository shape**
   - This is a single-purpose command-line utility, not a multi-service application.
   - The entire architecture is concentrated in `http_to_https.py`, with `README.md` documenting behavior and CLI contract.
   - There are no third-party dependencies, background services, or persistent stores.

2. **Primary function**
   - The tool scans a project directory for text files and rewrites `http://` links to `https://`.
   - The output is either a preview of intended changes or in-place file modifications.
   - The core data flow is: directory tree input → file filtering → content scan → candidate URL replacement → optional verification/backup → summary/report output.

3. **CLI and runtime boundary**
   - The script is designed to run both interactively and non-interactively.
   - CLI flags control scope and behavior: path, extensions, dry-run, backup, verification, exclusions, symlink handling, verbosity, quiet mode, and JSON reporting.
   - This makes the command line the main configuration boundary; there is no separate config file or API.

4. **File discovery subsystem**
   - The first major subsystem is project traversal starting from `--path` or the current working directory.
   - It walks the directory tree, optionally following symlinks, and filters out excluded directories and extensions.
   - Default exclusions cover common VCS, build, cache, virtualenv, and asset/binary directories to keep traversal focused on editable source files.

5. **Content classification and safety checks**
   - Before scanning content, files are screened for likely binary data using a null-byte check in the first 8 KB.
   - This is an important architectural boundary: the tool is explicitly text-oriented and avoids corrupting binary assets.
   - Symlink skipping by default is another safety control to prevent unintended traversal or repeated edits.

6. **Pattern matching and rewrite engine**
   - The transformation logic is centered on detecting `http://` occurrences and replacing them with `https://`.
   - Existing `https://` URLs are protected from double conversion via negative lookbehind behavior, so the rewrite is idempotent for already-secure links.
   - The matching phase also tracks line numbers and replacement counts, which feed both console output and reporting.

7. **Optional URL verification path**
   - When `--verify` is enabled, the script adds a network validation step before replacing a candidate URL.
   - It issues a `HEAD` request to the corresponding `https://` URL and only rewrites when the URL resolves successfully.
   - This creates a distinct external dependency boundary: local file rewriting can be gated by live network reachability.

8. **Modification and backup workflow**
   - In normal mode, matching files are rewritten in place.
   - With `--backup`, each modified file gets a sibling `.bak` copy before the rewrite, preserving the original state.
   - This implies a two-step write path: snapshot first, then mutate, which is important for safe recovery and rollback.

9. **Dry-run versus commit modes**
   - `--dry-run` switches the tool into a non-destructive preview mode.
   - In that mode, the same scan and match logic runs, but no file contents are changed; instead, the script prints what would change.
   - This is an architectural separation between analysis and mutation, useful for CI validation and human review.

10. **Output and operator feedback**
   - The script supports multiple output profiles: normal, verbose, and quiet.
   - Verbose mode surfaces every scanned file and skip reason; quiet mode reduces output to a final summary line.
   - This output layer is important because the tool is intended to be used in both manual sessions and automated pipelines.

11. **Audit and reporting subsystem**
   - `--report` writes a JSON audit file after the run.
   - The report captures timing, project path, selected extensions, dry-run state, summary counts, and per-file details.
   - This gives the tool a machine-readable telemetry boundary suitable for CI artifacts or change auditing.

12. **Operational safeguards**
   - The script warns when run inside a git repository with uncommitted changes, signaling that it is aware of source-control context.
   - Permission errors are handled by skipping files and marking them as denied rather than failing the whole run.
   - These safeguards show that reliability is prioritized over strict all-or-nothing behavior.

13. **Overall architectural picture**
   - The repository is a linear file-processing pipeline with a small number of clear stages: discover, filter, inspect, verify, rewrite, and report.
   - All logic is local and synchronous except for optional URL verification, which introduces network I/O.
   - For an architecture diagram, the key boundaries are the filesystem tree, the text/binary filter, the optional HTTP verification callout, and the output/reporting layer.

Main entry points: [`http_to_https.py`](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py) (CLI flags), [`README.md`](https://github.com/pardim93/http_to_https/blob/master/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["CLI utility"]
  node_script["Main script<br/>cli entrypoint<br/>[http_to_https.py]"]
  node_args["CLI flags<br/>configuration<br/>[http_to_https.py]"]
  node_discover["Discovery<br/>filesystem walk<br/>[http_to_https.py]"]
  node_filter["File filter<br/>scope filter<br/>[http_to_https.py]"]
  node_safety["Binary guard<br/>safety check<br/>[http_to_https.py]"]
  node_scan["Content scan<br/>text scan<br/>[http_to_https.py]"]
  node_match["Rewrite match<br/>pattern engine<br/>[http_to_https.py]"]
  node_verify["URL verify<br/>network check<br/>[http_to_https.py]"]
  node_modify["Rewrite files<br/>mutation<br/>[http_to_https.py]"]
  node_backup["Backup copy<br/>snapshot<br/>[http_to_https.py]"]
  node_report["Summary report<br/>output/reporting<br/>[http_to_https.py]"]
  node_guards["Operational guards<br/>safety/robustness<br/>[http_to_https.py]"]
end

node_readme["README<br/>docs<br/>[README.md]"]

node_readme -->|"documents"| node_script
node_script -->|"parses"| node_args
node_args -->|"drives"| node_discover
node_discover -->|"yields"| node_filter
node_filter -->|"screens"| node_safety
node_safety -->|"passes"| node_scan
node_scan -->|"finds"| node_match
node_match -.->|"optionally gates"| node_verify
node_match -->|"produces"| node_modify
node_args -->|"enables"| node_backup
node_backup -->|"precedes"| node_modify
node_modify -->|"summarizes"| node_report
node_guards -->|"annotates"| node_report
node_args -->|"formats"| node_report
node_script -->|"checks"| node_guards

click node_readme "https://github.com/pardim93/http_to_https/blob/master/README.md"
click node_script "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_args "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_discover "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_filter "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_safety "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_scan "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_match "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_verify "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_modify "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_backup "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_report "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"
click node_guards "https://github.com/pardim93/http_to_https/blob/master/http_to_https.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_script,node_args,node_discover,node_filter,node_safety,node_scan,node_match,node_verify,node_modify,node_backup,node_report,node_guards toneBlue
class node_readme toneNeutral
```

## Components

### CLI utility

Single-purpose command-line pipeline for scanning and rewriting HTTP links in project files.

- [Main script](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): cli entrypoint · All runtime logic lives here. · `http_to_https.py`
- [CLI flags](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): configuration · Path, dry-run, backup, verify, exclusions, symlinks, verbosity, quiet, report. · `http_to_https.py`
- [Discovery](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): filesystem walk · Traverses the project tree from the target path. · `http_to_https.py`
- [File filter](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): scope filter · Applies extension and exclusion rules while honoring symlink settings. · `http_to_https.py`
- [Binary guard](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): safety check · Skips likely binary files using a null-byte probe. · `http_to_https.py`
- [Content scan](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): text scan · Reads text files and locates http:// occurrences with line tracking. · `http_to_https.py`
- [Rewrite match](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): pattern engine · Detects replaceable links and avoids double-converting https://. · `http_to_https.py`
- [URL verify](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): network check · Optionally HEADs the https:// target before rewrite. · `http_to_https.py`
- [Rewrite files](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): mutation · Writes changes in place or previews them in dry-run mode. · `http_to_https.py`
- [Backup copy](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): snapshot · Creates sibling .bak files before mutation when enabled. · `http_to_https.py`
- [Summary report](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): output/reporting · Emits console summaries and optional JSON audit output. · `http_to_https.py`
- [Operational guards](https://github.com/pardim93/http_to_https/blob/master/http_to_https.py): safety/robustness · Handles permission skips and warns on uncommitted git changes. · `http_to_https.py`

### Other components

- [README](https://github.com/pardim93/http_to_https/blob/master/README.md): docs · Usage and CLI contract documentation. · `README.md`

## Connections

- README → Main script: documents · README explains behavior and command-line usage.
- Main script → CLI flags: parses · CLI is the main configuration boundary.
- CLI flags → Discovery: drives · Flags select target path and traversal behavior.
- Discovery → File filter: yields · Directory walk produces candidate files.
- File filter → Binary guard: screens · Non-target files are removed before content inspection.
- Binary guard → Content scan: passes · Only likely text files are scanned.
- Content scan → Rewrite match: finds · Searches for http:// occurrences and replacement spans.
- Rewrite match → URL verify: optionally gates · Verification can approve a candidate rewrite.
- Rewrite match → Rewrite files: produces · Matched replacements feed the rewrite step.
- CLI flags → Backup copy: enables · Backup behavior is controlled by CLI flags.
- Backup copy → Rewrite files: precedes · Snapshot is taken before in-place mutation.
- Rewrite files → Summary report: summarizes · File-level results roll up into console and JSON output.
- Operational guards → Summary report: annotates · Skips, denied files, and warnings affect the final outcome.
- CLI flags → Summary report: formats · Verbose, quiet, dry-run, and JSON report modes shape output.
- Main script → Operational guards: checks · Runtime safety checks run around the processing pipeline.
