# pywebio/pordle architecture

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

- Interactive diagram: https://gitdiagram.com/pywebio/pordle
- Repository: https://github.com/pywebio/pordle

## Overview

##### Project type and purpose (from README + file tree)
**Type:** Small single-file Python web app (interactive UI) built with **PyWebIO**.
**Purpose:** Implements a Wordle-like game (“PORDLE”) served from a local Python process; users play via a browser UI rendered/managed by PyWebIO.

- Game “word” is **hard-coded** (no DB / no word list service in this simplified repo version).
- No stats, no daily limits, no mobile/desktop keyboard integration (so fewer external components).
- Runtime is: `pip install pywebio` then `python pordle.py`.

##### What the file structure implies architecturally
Top-level files:
- `pordle.py`: **entire application** (UI + game logic + server startup entrypoint likely all together).
- `requirements.txt`: dependency declaration (at least `pywebio`; possibly others).
- `.drone.yml`: CI pipeline definition (build/test/lint steps if any).
- `README.md`: usage docs.

There are **no** separate `src/`, `templates/`, `static/`, `tests/`, `db/`, etc. directories, which implies:
- **Monolithic** app contained in a single process
- No persistent storage layer
- No explicit API layer (PyWebIO is UI-driven; not a REST backend + separate frontend)

##### Component (inside `pordle.py`: UI loop, game rules, state)

This avoids over-inventing components that aren’t present (e.g., databases, separate frontend bundles), while still being “very detailed” about the real runtime boundaries and flows.

##### User → Browser
- “types guess, submits”
##### Browser ⇄ PyWebIO Server (Python process)
- “UI events / session updates” over HTTP/WebSocket
##### PyWebIO Server → Game Rules/Evaluation
- “evaluate guess vs target”
##### Game Rules/Evaluation → Game State
- “update attempts, statuses”
##### PyWebIO Server → Browser
- “render updated grid/feedback”

Because the word is hard-coded and there is no persistence:

##### Architectural patterns/design principles actually present
- **Single-process monolith** (one Python runtime)
- **Server-driven UI** (PyWebIO renders UI from Python; not a compiled SPA frontend)
- **Session-oriented interaction**
- Each player has a session; game state is typically kept in-memory for that session.
- **No persistence** (ephemeral in-memory state)

- “State is in-memory per session; lost on process restart.”

- Protocol: HTTP/WebSocket session channel
- Components: Entrypoint, UI/Interaction, Game Logic, State

Examples:
- “Guess submission (string)”
- “Rendered UI diff / output commands”
- “Letter feedback statuses (per position)”
- “Session state update”

##### Explicitly show boundaries
This makes the “single-file architecture” explicit, which is the defining property of this repo.

- No DB, no Redis, no auth, no stats service (README explicitly says no stats and simplified behavior).
- No separate frontend build pipeline (no `frontend/`, no JS bundle).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 1: System Context
    %% =========================
    subgraph "System Context"
        U["Player (User)"]:::actor
        B["Web Browser"]:::client
        S["PORDLE (PyWebIO web app)"]:::server

        U -->|"types_guess_and_submits"| B
        B <-->|"PyWebIO_session_channel (HTTP/WebSocket)"| S
    end

    %% =========================
    %% Level 2: Container View
    %% =========================
    subgraph "Runtime Containers (Local Machine)"
        direction TB

        subgraph "Client Container"
            B2["Browser UI (renders server-driven UI)"]:::client
        end

        subgraph "Server Container (Single Python Process)"
            direction TB
            PY["Python Process"]:::server

            subgraph "pordle.py (Single-file Monolith)"
                direction TB
                ENTRY["App Entrypoint / Server Bootstrap"]:::component
                UI["UI Rendering / Interaction (PyWebIO APIs)"]:::component
                VAL["Validation"]:::component
                RULES["Game Rules / Guess Evaluation"]:::component
                STATE[("Game State (in-memory per session)\nHard-coded target word")]:::state
            end
        end
    end

    %% Container links
    B2 <-->|"UI_events_and_session_updates"| PY
    PY -->|"rendered_UI_output"| B2

    %% Internal component flows
    ENTRY -->|"starts_session_server"| UI
    UI -->|"guess_input (string)"| VAL
    VAL -->|"validated_guess"| RULES
    RULES -->|"letter_feedback (per_position)"| UI
    RULES -->|"state_mutation (attempts,statuses)"| STATE
    STATE -->|"current_session_state"| UI

    %% =========================
    %% Level 3: Build/Delivery (Non-runtime)
    %% =========================
    subgraph "Delivery / Lifecycle (Non-runtime)"
        direction TB
        DEV["Developer git push / PR"]:::external
        CI["Drone CI Pipeline"]:::ci
        REQ["Dependencies (pip requirements)"]:::doc
        DOC["README / Usage Docs"]:::doc

        DEV -->|"triggers_pipeline"| CI
        CI -->|"install_deps"| REQ
        CI -->|"checks_and_build_steps"| CI
    end

    %% Documentation relationships (informational)
    DOC -.->|"instructions: pip_install_then_run"| PY
    REQ -.->|"pywebio_dependency"| PY

    %% Notes / constraints
    N1["No DB / No external word list\nState is ephemeral per session; lost on restart"]:::note
    STATE -.->|"constraint"| N1

    %% =========================
    %% Click events (from mapping)
    %% =========================
    click S "https://github.com/pywebio/pordle/blob/master/pordle.py"
    click ENTRY "https://github.com/pywebio/pordle/blob/master/pordle.py"
    click UI "https://github.com/pywebio/pordle/blob/master/pordle.py"
    click STATE "https://github.com/pywebio/pordle/blob/master/pordle.py"
    click RULES "https://github.com/pywebio/pordle/blob/master/pordle.py"
    click VAL "https://github.com/pywebio/pordle/blob/master/pordle.py"
    click REQ "https://github.com/pywebio/pordle/blob/master/requirements.txt"
    click CI "https://github.com/pywebio/pordle/blob/master/.drone.yml"
    click DOC "https://github.com/pywebio/pordle/blob/master/README.md"

    %% =========================
    %% Styling
    %% =========================
    classDef actor fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1.5px
    classDef client fill:#dbeafe,stroke:#1d4ed8,color:#0f172a,stroke-width:1.5px
    classDef server fill:#dcfce7,stroke:#15803d,color:#052e16,stroke-width:1.5px
    classDef component fill:#bbf7d0,stroke:#16a34a,color:#052e16,stroke-width:1.2px
    classDef state fill:#ecfccb,stroke:#4d7c0f,color:#1a2e05,stroke-width:1.5px
    classDef ci fill:#ffedd5,stroke:#c2410c,color:#431407,stroke-width:1.5px
    classDef doc fill:#fef3c7,stroke:#b45309,color:#451a03,stroke-width:1.5px
    classDef external fill:#f3f4f6,stroke:#4b5563,color:#111827,stroke-width:1.2px
    classDef note fill:#fff7ed,stroke:#9a3412,color:#431407,stroke-dasharray: 4 3,stroke-width:1.2px
```
