# hobuinc/doppkit architecture

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

- Interactive diagram: https://gitdiagram.com/hobuinc/doppkit
- Repository: https://github.com/hobuinc/doppkit

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI["CLI Frontend"]:::presentation
        subgraph "CLI Commands"
            direction TB
            CLI_Cache["Cache Command"]:::presentation
            CLI_List["List Command"]:::presentation
            CLI_Sync["Sync Command"]:::presentation
        end
        GUI["GUI Frontend"]:::presentation
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        direction TB
        App["app.py\n(Core Orchestrator)"]:::core
        Cache["cache.py\n(Cache Module)"]:::core
        Grid["grid.py\n(Grid Client)"]:::core
        Upload["upload.py\n(Upload Module)"]:::core
        Util["util.py\n(Utility Module)"]:::core
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        LocalFS["Local File System"]:::integration
        USACE["USACE GRiD Service\n(HTTPS API)"]:::integration
    end

    %% Operations Layer
    subgraph "Operations & Docs"
        direction TB
        PyProj["pyproject.toml"]:::ops
        CliSpec["cli.spec"]:::ops
        GuiSpec["gui.spec"]:::ops
        Docs["docs/"]:::ops
        CI[".github/workflows/"]:::ops
    end

    %% Connections
    CLI -->|invokes| App
    CLI_Cache -->|uses| App
    CLI_List -->|uses| App
    CLI_Sync -->|uses| App
    GUI -->|invokes| App

    App -->|calls| Grid
    App -->|reads/writes| Cache
    App -->|calls| Upload
    App -->|uses| Util

    Upload -->|POSTs| Grid
    Cache -->|persists| LocalFS
    Grid -->|HTTPS| USACE

    %% Click Events
    click CLI "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/cli/__main__.py"
    click CLI_Cache "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/cli/cache.py"
    click CLI_List "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/cli/list.py"
    click CLI_Sync "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/cli/sync.py"
    click GUI "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/gui/__main__.py"
    click App "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/app.py"
    click Cache "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/cache.py"
    click Grid "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/grid.py"
    click Upload "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/upload.py"
    click Util "https://github.com/hobuinc/doppkit/blob/main/src/doppkit/util.py"
    click PyProj "https://github.com/hobuinc/doppkit/blob/main/pyproject.toml"
    click CliSpec "https://github.com/hobuinc/doppkit/blob/main/cli.spec"
    click GuiSpec "https://github.com/hobuinc/doppkit/blob/main/gui.spec"
    click Docs "https://github.com/hobuinc/doppkit/tree/main/docs/"
    click CI "https://github.com/hobuinc/doppkit/tree/main/.github/workflows/"

    %% Styles
    classDef presentation fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef core fill:#A8E6A3,stroke:#333,stroke-width:1px
    classDef integration fill:#FFCC80,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef ops fill:#D6CDEA,stroke:#333,stroke-width:1px
```
