Neon Moon

Version 1.2.1 — final stable portfolio release

Neon Moon is a neon-styled CustomTkinter desktop dashboard that combines live weather data with locally calculated lunar information for a verified U.S. ZIP code.

Important

AI-assisted development disclosure: I developed the project concept, defined the functional and visual requirements, selected features, tested each iteration, reported bugs, and directed revisions through the final release. ChatGPT generated the implementation code in response to that direction and feedback. I am publishing this project as an example of requirements development, product direction, iterative testing, quality assurance, interface design, and responsible AI-assisted software development—not as code I wrote independently from scratch.

My role

• Proposed a personally useful moon-phase and weather desktop application.
• Defined the dark neon visual direction, information-card layout, and first-run location workflow.
• Chose the weather, location, and lunar information presented by the dashboard.
• Reviewed all eight moon-phase signs and directed corrections to circular proportions and gibbous outlines.
• Tested successive versions on Ubuntu and reported interface, responsiveness, and modal-dialog defects.
• Verified the Ubuntu location-dialog fix used in Version 1.2.1.
• Established the final acceptance criteria for caching, partial-failure behavior, and refresh controls.

Main features

• Live current weather through Open-Meteo.
• U.S. ZIP-code verification through Zippopotam.us.
• Local lunar calculations through PyEphem.
• Automatic selection among eight custom neon moon-phase signs.
• Phase name, illumination, moon age, moonrise, moonset, and next full moon.
• Current temperature, apparent temperature, humidity, and conditions.
• Automatic weather refresh every 30 minutes.
• Automatic lunar refresh every 3 hours.
• Manual full refresh.
• Cached location, weather, and lunar information for offline startup.
• Partial-failure handling so one failed data source does not erase the other.
• Responsive CustomTkinter interface designed and tested primarily on Ubuntu.

Moon-phase artwork

The repository includes eight transparent neon PNG assets generated by the project itself. Each phase uses a true circular outer geometry. Waxing and waning gibbous signs display only the illuminated outer arc and curved terminator rather than an incorrect complete-circle outline.

Installation

Requirements

• Python 3.10 or newer
• Tkinter
• CustomTkinter
• Pillow
• Requests
• PyEphem

On Ubuntu, install Tkinter and virtual-environment support first:

sudo apt update
sudo apt install python3-tk python3-venv

Then clone and run the project:

git clone https://github.com/YOUR-USERNAME/neon-moon.git
cd neon-moon
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python main.py

No API key is required. The application uses public endpoints for ZIP-code geocoding and weather data.

First-run workflow

1. Launch the application.
2. Enter a five-digit U.S. ZIP code.
3. Neon Moon verifies the location through the geocoding service.
4. The app retrieves current weather and calculates lunar information.
5. The verified location and latest successful results are cached for future startup.

The location can be changed later with the Change Location button.

Data sources and calculations

• Zippopotam.us: ZIP-code geocoding.
• Open-Meteo: current weather conditions.
• PyEphem: local lunar phase, illumination, moon age, moonrise, moonset, and next-full-moon calculations.

Network responses are validated before they are converted into application data models.

Data and privacy

Neon Moon does not require an account or API credentials. It stores the selected ZIP code, verified location, and most recent successful weather and lunar results in a per-user settings file.

Typical Ubuntu location:

~/.config/neon_moon/settings.json

Typical locations on other systems:

Windows: %APPDATA%\NeonMoon\settings.json
macOS:   ~/Library/Application Support/NeonMoon/settings.json

The settings file is outside the project directory and is not included in this repository. Delete it to reset Neon Moon to its first-run state.

Refresh and failure behavior

• The clock updates every second.
• Weather refreshes every 30 minutes.
• Lunar information refreshes every 3 hours.
• The Refresh button updates both sources immediately.
• Changing the ZIP code clears cached data belonging to the previous location.
• A temporary weather failure does not erase valid lunar information.
• A temporary lunar-calculation failure does not erase valid weather information.
• Cached results remain visible when a network request cannot be completed.

Portfolio screenshot note

The dashboard screenshot in this README uses fictional cached demonstration data for Columbus, Ohio. It is included to show the completed interface without publishing a personal saved ZIP code or relying on a live network request during repository preparation.

Verification

The cleaned portfolio copy was checked by:

• Compiling all Python source files.
• Importing the non-GUI modules.
• Parsing representative geocoding and weather responses.
• Exercising settings serialization and cache matching in a temporary directory.
• Regenerating and inspecting all eight moon-phase assets.
• Launching the GUI under a virtual display with cached demonstration data.

The original project did not include a formal automated PyTest suite, so this repository documents that limitation rather than claiming automated coverage.

Project structure

neon-moon/
├── main.py
├── neon_moon_app.py
├── constants.py
├── models.py
├── settings_service.py
├── geocoding_service.py
├── weather_service.py
├── lunar_service.py
├── refresh_scheduler.py
├── asset_generator.py
├── assets/
│   ├── backgrounds/
│   └── moon_phases/
├── screenshots/
├── CHANGELOG.md
└── requirements.txt

Current limitations

• Location input is limited to five-digit U.S. ZIP codes.
• Live weather and location verification depend on third-party service availability.
• Cached data may be older than the current conditions when the application starts offline.
• Moonrise and moonset represent the next events after the calculation time and may correctly be labeled for the following day.
• At extreme latitudes, PyEphem may report moonrise or moonset as unavailable.
• The application does not include forecasts, weather alerts, cloud synchronization, or multiple saved locations.
• A formal automated test suite is not included in this version.

Third-party services

Weather and geocoding data are provided by their respective public services. Their inclusion does not imply sponsorship or affiliation. The neon background and moon-phase artwork are generated by this project.