# wolfpaulus/wordgame architecture

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

- Interactive diagram: https://gitdiagram.com/wolfpaulus/wordgame
- Repository: https://github.com/wolfpaulus/wordgame

## Overview

##### Project type and purpose
- This is a single-container, full-stack Python web application (built with Streamlit) that implements a simple word-guessing game. It also includes a CLI mode (via app.py) and a web UI (Streamlit + styles.css).
- The README describes the core game logic (random word selection, guess validation, hint generation) plus a web UI and CI/CD deployment.

##### File structure
- Top-level:
- Dockerfile, healthcheck.sh → containerization and runtime health check
- arm/app_service.json → ARM template for Azure App Service deployment
- .github/workflows → CI pipelines (tests + Docker publish)
- src/ → application code
– app.py → entry point (Streamlit UI + CLI glue)
– game.py → game logic
– styles.css → web styling
- words.txt (and tests/words.txt) → word list resource
- tests/ → pytest suite (test_game.py + test requirements)
- Configuration files: requirements.txt, pytest.ini, .streamlit/config.toml

##### Key README insights
- Describes both CLI and WebApp usage
- Deployment targets: Docker container running on a Linux server (via Azure App Service)
- CI/CD via GitHub Actions for testing and publishing images

##### Main components
A. Developer/GitHub Repo
- Source files, tests, CI workflows
B. CI/CD Pipeline (GitHub Actions)
- python-test workflow → runs pytest
- docker-publish workflow → builds Docker image, pushes to registry
C. Container Registry
- Docker Hub or Azure Container Registry
D. Deployment Infrastructure
- Azure App Service (ARM template) hosting the container
- healthcheck.sh used by App Service or Uptime Robot
- Uptime Robot monitors the public endpoint
E. Runtime Container
- Python runtime with dependencies (requirements.txt)
- Streamlit server exposing HTTP endpoint
- Static resource words.txt loaded into memory
- game.py logic invoked per user request
F. End User
- Web browser (UI served by Streamlit)
- CLI terminal (optional)

##### Relationships and data flows
- Developer pushes code → GitHub Actions is triggered
- python-test workflow → validate code via pytest → pass/fail
- On merge or tag → docker-publish workflow builds image → pushes to registry
- Azure App Service pulls latest image (per ARM template or CD trigger) → runs container
- Uptime Robot sends periodic HTTP pings → healthcheck.sh → status dashboard
- End user connects over HTTP → Streamlit UI served → invokes game logic → reads words.txt → returns HTML/CSS response

##### Architectural patterns and design principles
- 12-factor app: one codebase, declarative config, stateless container, backing file as resource
- Containerization: isolates dependencies, simplifies deployment
- CI/CD pipelines: automated testing and image publishing
- Infrastructure as Code: ARM template for Azure App Service

##### Technologies / frameworks to annotate
- Python 3.x, Streamlit
- Docker, Dockerfile instructions
- GitHub Actions (YAML workflows)
- Azure App Service (ARM JSON)
- pytest for tests
- Uptime Robot (external health monitor)

##### Be detailed but focused
- Don’t over-partition—group related files (app.py + game.py + CSS) into one “Application Container”
- Critical flows: build/test, publish/deploy, user/monitoring

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source & CI/CD Layer
    subgraph "Source & CI/CD" 
        direction TB
        Repo["GitHub Repo\n(Source Code)"]:::codeCi
        CI_Test["GitHub Actions:\npython-test"]:::codeCi
        CI_Publish["GitHub Actions:\ndocker-publish"]:::codeCi
        Tests["pytest suite\ntest_game.py"]:::codeCi
        Repo -->|push code triggers| CI_Test
        Repo -->|push code triggers| CI_Publish
        CI_Test -->|"runs tests"| Tests
    end

    %% Container Registry
    Registry["Docker Registry\n(Docker Hub / ACR)"]:::cloud

    %% Cloud Hosting Layer
    subgraph "Cloud Infrastructure"
        direction TB
        AppService["Azure App Service\n(runs container)"]:::cloud
    end

    %% Runtime Container
    subgraph "Runtime Container" 
        direction TB
        Container["Docker Container"]:::runtime
        Streamlit["Streamlit Server\n(http endpoint)"]:::runtime
        AppLogic["game.py Logic"]:::runtime
        Words["words.txt (static resource)"]:::runtime
        HealthCheck["healthcheck.sh\n(container health)"]:::runtime
        Container --> Streamlit
        Streamlit --> AppLogic
        AppLogic --> Words
        AppService --> Container
    end

    %% External Monitoring
    Uptime["Uptime Robot"]:::external
    Uptime -->|HTTP ping| HealthCheck

    %% End User
    Browser["End User Browser\nStreamlit UI"]:::external
    CLI["End User CLI\n(app.py)"]:::external
    Browser -->|HTTP request| Streamlit
    CLI -->|CLI invocation| Streamlit

    %% CI/CD to Registry & Deployment
    CI_Publish -->|build & push image| Registry
    Registry -->|pull image| AppService

    %% Click Events
    click Repo "https://github.com/wolfpaulus/wordgame/blob/main/.gitignore"
    click CI_Test "https://github.com/wolfpaulus/wordgame/blob/main/.github/workflows/python-test.yml"
    click CI_Publish "https://github.com/wolfpaulus/wordgame/blob/main/.github/workflows/docker-publish.yml"
    click Tests "https://github.com/wolfpaulus/wordgame/blob/main/tests/test_game.py"
    click Streamlit "https://github.com/wolfpaulus/wordgame/blob/main/src/app.py"
    click AppLogic "https://github.com/wolfpaulus/wordgame/blob/main/src/game.py"
    click Words "https://github.com/wolfpaulus/wordgame/blob/main/words.txt"
    click HealthCheck "https://github.com/wolfpaulus/wordgame/blob/main/healthcheck.sh"
    click Container "https://github.com/wolfpaulus/wordgame/tree/main/Dockerfile"
    click Container "https://github.com/wolfpaulus/wordgame/blob/main/.dockerignore"
    click Streamlit "https://github.com/wolfpaulus/wordgame/blob/main/.streamlit/config.toml"
    click AppService "https://github.com/wolfpaulus/wordgame/blob/main/arm/app_service.json"
    click Tests "https://github.com/wolfpaulus/wordgame/blob/main/tests/requirements.txt"
    click Registry "https://github.com/wolfpaulus/wordgame/blob/main/requirements.txt"
    click Tests "https://github.com/wolfpaulus/wordgame/blob/main/tests/words.txt"
    click Tests "https://github.com/wolfpaulus/wordgame/blob/main/pytest.ini"

    %% Styles
    classDef codeCi fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef runtime fill:#E6F5D0,stroke:#2E8B57,color:#2E8B57
    classDef cloud fill:#FFE5B4,stroke:#FFA500,color:#B35900
    classDef external fill:#FFF4C1,stroke:#FFD700,color:#8B7500
```
