# jaygaha/python-beginner architecture

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

- Interactive diagram: https://gitdiagram.com/jaygaha/python-beginner
- Repository: https://github.com/jaygaha/python-beginner

## Overview

##### Project Type and Purpose
- This is an educational “cookbook” of Python code samples and demos, organized by topic (basics, DSA, OOP, concurrency, frameworks, GUI, etc.).
- It uses Docker (via `.docker/python/Dockerfile` + `docker-compose.yml`) to provide a reproducible Python 3 environment so students can run every example without installing anything on the host.

##### File Structure
- Top-level orchestration:
- `.docker/python/Dockerfile` – builds the Python runtime image
- `docker-compose.yml` – defines the service, volume mounts, port mappings
- `pyproject.toml` & `workspace/requirements.txt` – declare dependencies
- Core content:
- `workspace/1_basic`, `workspace/2_dsa`, `workspace/3_oops`, `workspace/4_concurrency`, `workspace/7_framework`, `99_PyQtGUI`, etc. – each folder is a self-contained module of Python scripts.
- `assets/` – static files (mp3, fonts) used by GUI or other demos.
- Entry points:
- `workspace/main.py` or root `main.py` to launch sample sets (if present).
- Framework demos expose HTTP endpoints (aiohttp, gevent, Pyramid, Dash) on mapped ports.

##### README for Additional Insights
- Emphasizes building and spinning up the container with:
`docker compose build` → `docker compose up -d`
- No external services beyond Docker and the Internet (for pip installs).

a. Main Components
1. Developer Machine (host)
2. Version Control System (Git)
3. Docker Compose Orchestration
4. Docker Engine
5. Python Container (built from `.docker/python/Dockerfile`)
6. Mounted Volumes:
– `./workspace` → `/app/workspace`
– `./assets` → `/app/assets`
7. Code Modules inside the container:
– Basic, DSA, OOP, Concurrency, Framework demos, GUI samples
8. Dependency Layer (pyproject.toml, requirements.txt)
9. Framework-specific subservices (HTTP servers in `7_framework/*`)
10. Output files (e.g., logs, `output*.txt`, CSV/JSON in OOP exercises)
b. Relationships & Interactions
- Developer runs `docker compose up` → Compose reads `docker-compose.yml` → invokes Docker Engine
- Docker Engine builds the image via `.docker/python/Dockerfile` (pip installs from `pyproject.toml` + `requirements.txt`)
- Container starts, mounts `workspace` & `assets` as volumes
- Inside the container, Python scripts run on demand (CLI or HTTP servers for framework demos)
- HTTP ports exported (e.g., 8000, 8080) map back to the host, enabling web-based demos
- Scripts write outputs back to the mounted volume so host can inspect them
c. Architectural Patterns & Principles
- Containerization for environment consistency
- Single-service container pattern (one container runs all examples)
- Modularity: each topic folder is a logical subsystem with its own examples
- Volume-based code/dependency separation (code lives outside the image, making iteration fast)
d. Technologies & Frameworks
- Docker & Docker Compose
- Python 3.x (managed by pyproject.toml)
- Web frameworks: aiohttp, gevent HTTP server, Pyramid, Plotly Dash
- GUI: PyQt5/6 (99_PyQtGUI), using assets for media/fonts
- Concurrency modules: threading, multiprocessing, asyncio demos

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Layer
    subgraph "Developer Host" 
        direction TB
        DevMachine["Developer Machine"]:::external
        VCS["Version Control (Git)"]:::external
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Compose["Docker Compose Orchestration"]:::service
        click Compose "https://github.com/jaygaha/python-beginner/blob/main/docker-compose.yml"
    end

    %% Docker Engine
    DockerEngine["Docker Engine"]:::service

    %% Build Stage
    subgraph "Image Build"
        direction TB
        Dockerfile["Python Container Dockerfile"]:::service
        click Dockerfile "https://github.com/jaygaha/python-beginner/tree/main/.docker/python/Dockerfile"
        pyproject["pyproject.toml"]:::dependency
        click pyproject "https://github.com/jaygaha/python-beginner/blob/main/pyproject.toml"
        requirements["workspace/requirements.txt"]:::dependency
        click requirements "https://github.com/jaygaha/python-beginner/blob/main/workspace/requirements.txt"
        PipRegistry["pip Registry"]:::external
    end

    %% Runtime Container
    subgraph "Python Container" 
        direction TB
        subgraph "Dependencies"
            direction TB
            Image["Python 3.x Image"]:::service
        end
        subgraph "Volumes"
            direction TB
            WorkspaceVol["Workspace Volume"]:::volume
            AssetsVol["Assets Volume"]:::volume
        end
        subgraph "Code Modules"
            direction TB
            Basic["Basic Samples"]:::module
            click Basic "https://github.com/jaygaha/python-beginner/tree/main/workspace/1_basic/"
            DSA["DSA Samples"]:::module
            click DSA "https://github.com/jaygaha/python-beginner/tree/main/workspace/2_dsa/"
            OOP["OOP Samples"]:::module
            click OOP "https://github.com/jaygaha/python-beginner/tree/main/workspace/3_oops/"
            Concurrency["Concurrency Samples"]:::module
            click Concurrency "https://github.com/jaygaha/python-beginner/tree/main/workspace/4_concurrency/"
            PackageMgr["Package Modules"]:::module
            click PackageMgr "https://github.com/jaygaha/python-beginner/tree/main/workspace/5_package_managers/"
            Typing["Typing & Analysis"]:::module
            click Typing "https://github.com/jaygaha/python-beginner/tree/main/workspace/6_typing/"
            Udacity["Udacity Modules"]:::module
            click Udacity "https://github.com/jaygaha/python-beginner/tree/main/workspace/50_udacity/"
            FreeCode["FreeCodeCamp Modules"]:::module
            click FreeCode "https://github.com/jaygaha/python-beginner/tree/main/workspace/61_freecodecamp/"
            subgraph "Framework Demos"
                direction TB
                Aiohttp["aiohttp Service"]:::endpoint
                click Aiohttp "https://github.com/jaygaha/python-beginner/tree/main/workspace/7_framework/aiohttp/"
                Gevent["gevent Service"]:::endpoint
                click Gevent "https://github.com/jaygaha/python-beginner/tree/main/workspace/7_framework/gevent/"
                Plotly["Plotly Dash Service"]:::endpoint
                click Plotly "https://github.com/jaygaha/python-beginner/tree/main/workspace/7_framework/plotly_dash/"
                Pyramid["Pyramid Service"]:::endpoint
                click Pyramid "https://github.com/jaygaha/python-beginner/tree/main/workspace/7_framework/pyramid/"
            end
            PyQt["PyQt GUI Samples"]:::module
            click PyQt "https://github.com/jaygaha/python-beginner/tree/main/workspace/99_PyQtGUI/"
            Assets["Static Assets"]:::module
            click Assets "https://github.com/jaygaha/python-beginner/tree/main/workspace/assets/"
        end
        subgraph "Entry Points"
            direction TB
            RootMain["Root main.py"]:::module
            click RootMain "https://github.com/jaygaha/python-beginner/blob/main/main.py"
            WorkspaceMain["Workspace main.py"]:::module
            click WorkspaceMain "https://github.com/jaygaha/python-beginner/blob/main/workspace/main.py"
        end
        subgraph "Outputs"
            direction TB
            Logs["Log / output files"]:::volume
        end
    end

    %% External Host
    HostDisplay["Host Display (GUI)"]:::external

    %% Network Endpoints
    HostPort8000["Host Port 8000"]:::external
    HostPort8080["Host Port 8080"]:::external

    %% Relationships
    DevMachine -->|clones| VCS
    VCS -->|docker compose up| Compose
    Compose -->|invokes| DockerEngine
    DockerEngine -->|builds image using| Dockerfile
    Dockerfile -->|reads| pyproject
    Dockerfile -->|reads| requirements
    Dockerfile -->|pulls from| PipRegistry
    DockerEngine -->|runs| Image

    Image -->|mounts| WorkspaceVol
    Image -->|mounts| AssetsVol

    WorkspaceVol --> Basic
    WorkspaceVol --> DSA
    WorkspaceVol --> OOP
    WorkspaceVol --> Concurrency
    WorkspaceVol --> PackageMgr
    WorkspaceVol --> Typing
    WorkspaceVol --> Udacity
    WorkspaceVol --> FreeCode
    WorkspaceVol --> Aiohttp
    WorkspaceVol --> Gevent
    WorkspaceVol --> Plotly
    WorkspaceVol --> Pyramid
    WorkspaceVol --> PyQt
    AssetsVol --> Assets

    Image -->|executes| RootMain
    Image -->|executes| WorkspaceMain

    Aiohttp -->|exposes port| HostPort8000
    Gevent -->|exposes port| HostPort8080
    Plotly -->|exposes port| HostPort8000
    Pyramid -->|exposes port| HostPort8080

    PyQt -->|renders on| HostDisplay

    Basic -->|writes logs to| Logs
    DSA -->|writes outputs to| Logs
    OOP -->|writes outputs to| Logs
    Concurrency -->|writes logs to| Logs

    Logs -->|stored in| WorkspaceVol

    %% Styles
    classDef service fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef external fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a;
    classDef dependency fill:#ffe082,stroke:#ff6f00,color:#ff6f00;
    classDef volume fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef module fill:#ffcc80,stroke:#e65100,color:#e65100;
    classDef endpoint fill:#ce93d8,stroke:#8e24aa,color:#8e24aa;
```
