The Problem

People who need a free domain often lack a simple, self‑hosted registration front‑end and a minimal WHOIS service. The repo tries to fill that gap by providing static HTML pages for user interaction and a lightweight Python WHOIS endpoint, but the code base is small, undocumented, and untested.

What This Does

The repository ships a static front‑end under opensource/frontend/ (e.g., register.html, domain_view.html) that presents registration forms and informational pages. The back‑end consists of two executable modules:

  • opensource/whois_server/whois.py – a tiny HTTP/WHOIS server that answers queries about the free domains.
  • opensource/static/config/cookieconsent-config.js – client‑side configuration for the cookie‑consent banner shown on the HTML pages.

All other files are markdown documentation (documents/…) or image assets used by the front‑end.

How It Is Wired

Entry point – The only runnable script is whois.py. Running it (python opensource/whois_server/whois.py) starts a listening socket (default port hard‑coded in the file). The script parses incoming WHOIS requests, looks up domain data from an internal (likely in‑memory) store, and returns a plain‑text response.

  • whois.py owns all network I/O for the service. It does not import any other internal modules, so the import graph shows a single isolated node.
  • The HTML front‑end files are served separately (e.g., by a web server such as Nginx or Apache) and reference cookieconsent-config.js for the consent UI. No server‑side code links the front‑end to whois.py; integration must be performed by the operator.

Because the internal call graph contains no edges, there is no coupling between the Python WHOIS server and the static front‑end. The only “wide blast radius” is whois.py; any change to its request handling logic directly affects all WHOIS queries. No circular dependencies exist.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/FreeDomain
cd FreeDomain

# (Optional) Create a virtual environment
python -m venv venv
source venv/bin/activate

# Run the WHOIS service (default port 8080, see whois.py for details)
python opensource/whois_server/whois.py

No requirements.txt, pyproject.toml, or Dockerfile is present, so any third‑party libraries used by whois.py must be installed manually after inspecting the source.

To serve the static pages, configure an external web server to point its document root at opensource/frontend/ and ensure it can reach the WHOIS service (e.g., via a reverse proxy or direct socket connection). No configuration files are provided for this step.

Real‑World Use

A small ISP could deploy the WHOIS script on a low‑cost VM, expose port 8080, and point a public web server to the frontend/ directory. When a user submits a registration form (handled outside this repo), the operator would add the new domain to the in‑memory store used by whois.py, making the domain immediately resolvable via the WHOIS endpoint.

Code Health & Issues

  • Medium – Deep nesting – opensource/static/config/cookieconsent-config.js and opensource/whois_server/whois.py each have a maximum indentation depth of 7, making the control flow hard to follow. Refactor with early returns or helper functions.
  • Medium – No tests – The repository contains no test files; code paths are unverified.
  • Medium – No CI/CD – No continuous‑integration configuration is present in .github/ or elsewhere.
  • Low – License present – A LICENSE file exists, satisfying basic legal hygiene.
  • Low – No Dockerfile or lockfile – Build reproducibility and containerisation are missing.

No secrets were detected in the commit history.

The Bottom Line

FreeDomain provides a minimal static UI and a single‑file Python WHOIS server that can be spun up quickly, but it lacks integration, testing, and automation. It is suitable only for prototyping or for operators comfortable adding the missing glue (web server config, persistence, tests). Teams needing a production‑grade free‑domain service will need to extend the code base significantly.