How hobuinc/doppkit works
Project Type and Purpose
• Project Type: A client-side tool with two user interfaces (CLI and GUI) for interacting with an external web service (USACE GRiD).
• Purpose: Download and manage AOI exports in potentially unreliable network conditions, offering both a terminal UI and a Qt-based desktop UI.
File Structure
Top-level folders and files of interest:
• src/doppkit – Core library
– app.py: Entry point for shared application logic
– cache.py: Local caching layer
– grid.py: HTTP client for GRiD service
– upload.py: Logic to upload data back to GRiD
– util.py: Shared utilities
• src/doppkit/cli – CLI interface
– __main__.py: CLI launcher
– cache.py, list.py, sync.py: Individual CLI commands using rich for progress & logging
• src/doppkit/gui – GUI interface (PySide6/Qt)
– __main__.py: GUI launcher
– Window, Views (ExportView, UploadView), Dialogs, Widgets
– MenuBar, resource files
• docs – Documentation setup (Sphinx)
• pyproject.toml – Build and dependency declarations
• gui.spec, cli.spec – Packaging scripts for generating single-file executables
Extract Insights from README
• Two front ends: doppkit (CLI) and doppkit-gui (Qt GUI).
• Core operations: authenticate with GRID_ACCESS_TOKEN, list and sync exports.
• Caching: support offline/retries.
• Packaging: single-binary builds for Windows.
Components
a. User Interfaces (Left side)
– CLI Frontend
– GUI Frontend
b. Core Library (Center)
– Application Layer (app.py orchestrator)
– Cache Module (cache.py) – interacts with local filesystem
– Grid Client (grid.py) – HTTP REST client
– Upload Module (upload.py)
– Utility Module (util.py)
c. External Systems (Right side)
– USACE GRiD Service (HTTPS API)
– Local File System (cache storage)
d. Packaging & DevOps (Optional overlay)
– pyproject.toml, gui.spec, cli.spec
– CI workflows (.github/workflows)
Architectural Patterns & Design Principles
• Separation of concerns:
– UI adapters (CLI, GUI) vs. core logic vs. external integration
• Modular design: each responsibility in its own module
• Adapter pattern: CLI/GUI code adapts user actions to core service calls
• Resilience: cache module sits between core logic and network failures