# millern/verbformen-cli architecture

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

- Interactive diagram: https://gitdiagram.com/millern/verbformen-cli
- Repository: https://github.com/millern/verbformen-cli

## Overview

1. **Project shape**
   - This repository is a small Python package that exposes both a **CLI** and a **library API** for looking up German words on **verbformen.com**.
   - The architecture is intentionally thin: it fetches data from one external source, parses it, turns it into typed models, and renders either a terminal card or a Python dict-like result.

2. **Primary entrypoints**
   - `verbformen_cli/cli.py` is the command-line entrypoint.
   - `verbformen_cli/__init__.py` re-exports the public library surface, likely including `Client` and enums such as `PartOfSpeech`, so users can import from `verbformen_cli` directly.
   - The README’s `verbformen` command maps to this CLI layer.

3. **Core workflow**
   - User input enters through the CLI or `Client.search(...)`.
   - The client sends a request to verbformen.com, receives the page/response, parses the linguistic information, and returns structured data.
   - That structured data is then either displayed in the terminal or consumed directly by Python code.

4. **Networking / external boundary**
   - `verbformen_cli/downloaders.py` represents the HTTP/data acquisition boundary.
   - This is the only subsystem that should know how to talk to the external site.
   - The repo has no sign of internal storage, queues, or background jobs; the system is request/response only.

5. **Parsing and extraction**
   - `verbformen_cli/parsers.py` is the transformation layer from fetched content into usable fields.
   - It likely extracts:
     - search term
     - definitions
     - part of speech
     - conjugation/declension forms
     - grammatical metadata such as level, behavior, auxiliary verb, gender, endings
   - This layer is where the site-specific HTML structure is interpreted, so it is the most fragile boundary with the external service.

6. **Domain model**
   - `verbformen_cli/models.py` holds the structured representation of results.
   - The README examples show fields like `search`, `definitions`, `part_of_speech`, `behavior`, `present`, `imperfect`, `perfect`, `auxiliary_verb`, `flection`, `use`, and `level`.
   - This suggests the package models different grammatical categories in a single result object, with `PartOfSpeech` as a shared enum or classification.

7. **Client facade**
   - `verbformen_cli/clients.py` is the main orchestration layer.
   - It likely combines downloader + parser + models behind a simple API such as `Client.default_client()` and `Client.search(...)`.
   - This is the best place to diagram as the application’s service boundary: it hides scraping details from consumers.

8. **Presentation layer**
   - `verbformen_cli/display.py` is responsible for terminal formatting.
   - The README shows box-drawn summary cards with color/style-like layout, so this layer converts parsed results into a human-friendly CLI view.
   - It is separate from parsing, which keeps presentation concerns out of the data extraction logic.

9. **Configuration**
   - `verbformen_cli/settings.py` likely stores runtime constants such as base URL, request headers, timeouts, or lookup defaults.
   - This is a lightweight configuration boundary rather than a full settings system.

10. **Testing**
    - `tests/test_verbformen_cli.py` indicates the main verified behavior is the end-to-end CLI/library interaction.
    - Since the project depends on an external site, tests likely focus on parsing behavior, CLI output, and client wiring rather than broad application state.

11. **Development/tooling**
    - `pyproject.toml`, `mypy.ini`, `.flake8`, and `Makefile` show a standard Python packaging and quality-tooling setup.
    - `development/README.md` suggests extra local development notes or commands, but not a separate runtime subsystem.

12. **What to draw in an architecture diagram**
    - The key boxes are:
      - **User / terminal or Python caller**
      - **CLI / Client facade**
      - **Downloader**
      - **Parser**
      - **Domain models**
      - **Display**
      - **External service: verbformen.com**
    - The main arrows are:
      - user input → CLI/client
      - client → downloader → verbformen.com
      - response → parser → models
      - models → display or returned API result
    - There are no obvious internal microservices, databases, or async pipelines; this is a compact, synchronous scraping-and-formatting package.

Main entry points: [`verbformen_cli/clients.py`](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/clients.py) (Client facade), [`verbformen_cli/cli.py`](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/cli.py) (CLI entry), [`verbformen_cli/models.py`](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/models.py) (Models), [`verbformen_cli/parsers.py`](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/parsers.py) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["verbformen_cli package"]
  node_cli_entry["CLI entry<br/>command<br/>[cli.py]"]
  node_public_api["Public API<br/>re-export<br/>[__init__.py]"]
  node_client_facade["Client facade<br/>[clients.py]"]
  node_downloader["Downloader<br/>http boundary<br/>[downloaders.py]"]
  node_parser["Parser<br/>extractor<br/>[parsers.py]"]
  node_models["Models<br/>domain model<br/>[models.py]"]
  node_display["Display<br/>formatter<br/>[display.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
end

subgraph group_external["External service"]
  node_verbformen_site[("verbformen.com<br/>external source")]
end

node_user_terminal(("User<br/>actor"))
node_python_caller(("Python caller<br/>actor"))

node_user_terminal -->|"runs command"| node_cli_entry
node_python_caller -->|"imports"| node_public_api
node_cli_entry -->|"calls search"| node_client_facade
node_public_api -->|"re-exports"| node_client_facade
node_client_facade -->|"reads config"| node_settings
node_client_facade -->|"fetches page"| node_downloader
node_downloader -->|"HTTP request"| node_verbformen_site
node_verbformen_site -->|"response content"| node_parser
node_parser -->|"builds result"| node_models
node_client_facade -->|"coordinates"| node_parser
node_models -->|"renders"| node_display
node_models -->|"returns data"| node_python_caller
node_cli_entry -->|"prints output"| node_display

click node_cli_entry "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/cli.py"
click node_public_api "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/__init__.py"
click node_client_facade "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/clients.py"
click node_downloader "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/downloaders.py"
click node_parser "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/parsers.py"
click node_models "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/models.py"
click node_display "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/display.py"
click node_settings "https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/settings.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_cli_entry,node_public_api,node_client_facade,node_downloader,node_parser,node_models,node_display,node_settings toneBlue
class node_verbformen_site toneAmber
class node_user_terminal,node_python_caller toneNeutral
```

## Components

### verbformen_cli package

Core CLI, scraping, parsing, and presentation code.

- [CLI entry](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/cli.py): command · Command-line entrypoint and argument handling · `verbformen_cli/cli.py`
- [Public API](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/__init__.py): re-export · Package surface exposed for direct imports · `verbformen_cli/__init__.py`
- [Client facade](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/clients.py): service · Orchestrates lookups behind a simple search API · `verbformen_cli/clients.py`
- [Downloader](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/downloaders.py): http boundary · Fetches pages from the remote site · `verbformen_cli/downloaders.py`
- [Parser](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/parsers.py): extractor · Converts fetched content into structured fields · `verbformen_cli/parsers.py`
- [Models](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/models.py): domain model · Typed result objects and grammatical enums · `verbformen_cli/models.py`
- [Display](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/display.py): formatter · Renders terminal-friendly result cards · `verbformen_cli/display.py`
- [Settings](https://github.com/millern/verbformen-cli/blob/master/verbformen_cli/settings.py): config · Runtime constants and lookup defaults · `verbformen_cli/settings.py`

### External service

Remote lookup source.

- **verbformen.com**: external source · Remote dictionary and conjugation site

### Other components

- **User**: actor · CLI user at the terminal
- **Python caller**: actor · Library consumer importing the package

## Connections

- User → CLI entry: runs command · User invokes the CLI lookup command
- Python caller → Public API: imports · Library consumers import the package surface
- CLI entry → Client facade: calls search · CLI delegates lookup work to the client
- Public API → Client facade: re-exports · Public package API exposes the client facade
- Client facade → Settings: reads config · Client uses shared lookup defaults and constants
- Client facade → Downloader: fetches page · Facade requests remote content through the HTTP boundary
- Downloader → verbformen.com: HTTP request · Downloads lookup content from the external site
- verbformen.com → Parser: response content · Fetched page content is handed to parsing logic
- Parser → Models: builds result · Parser turns extracted fields into typed results
- Client facade → Parser: coordinates · Client wires fetching and parsing into one search flow
- Models → Display: renders · Terminal display formats structured results for humans
- Models → Python caller: returns data · Library callers consume the structured result directly
- CLI entry → Display: prints output · CLI sends results to the terminal formatter