# zamanayaz/pytodo architecture

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

- Interactive diagram: https://gitdiagram.com/zamanayaz/pytodo
- Repository: https://github.com/zamanayaz/pytodo

## Overview

##### Project type and purpose (from README + file tree)
**Type:** Single-file Python **CLI application**
**Purpose:** A simple To‑Do manager run from terminal with menu-driven commands:
- Task
- View tasks
- Task as done
- View completed tasks
- Exit

##### What the file structure implies architecturally
File tree:
- `pytodo-cli.py` → the runtime entrypoint; contains all domain logic + UI + storage decisions
- `README.md` → usage documentation

Open `pytodo-cli.py` and identify (even if they’re just functions/blocks):
##### Menu/UI layer: prints menu, reads input, validates selection
3. **Command handlers**: functions like `add_task()`, `view_tasks()`, `mark_done()`, `view_completed()`
##### Storage
- In-memory list only? (data lost on exit)
- Or file-based persistence? (e.g., read/write a `.txt`/`.json` file)

##### Application Layer (Use Cases)
- Task
- View Tasks
- As Done
- View Completed Tasks
##### Domain Layer
- Task entity (representation + status)
- Task List / Task Repository interface (conceptually)
##### Infrastructure Layer (if present)
- In-memory store (list)
- File persistence adapter (read/write file)

- CLI Presentation → Use Case: “User command + parameters”
- Use Case → Domain/Repository: “Create/update/query tasks”
- Repository ↔ Persistence: “serialize/deserialize tasks” (only if file exists)
- Use Case → CLI Presentation: “Result/status + data to render”

##### “Don’t overthink it” but be detailed: how to split into as many components as possible
- Input validation component
- Command routing/dispatch component
- Separate handlers for each command
- Task formatter/printer component
- Task storage component (in-memory)
- Optional persistence component (file IO)
- Startup/shutdown lifecycle (load tasks at start, save before exit)

Even if these are not separate Python modules today, showing them as components is still accurate if they exist as functions/blocks/responsibilities in `pytodo-cli.py`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Actors / External Systems
    %% =========================
    U["User (Terminal/Console)"]:::actor
    FS[("Local File System\n(Optional tasks file)")]:::external

    %% =========================
    %% System (Single-file CLI)
    %% =========================
    subgraph "PyTodo CLI System"
        APP["PyTodo CLI Application\n(pytodo-cli.py)"]:::system

        subgraph "CLI Presentation Layer"
            MENU["Menu Renderer\n(prints options)"]:::ui
            INP["Input Reader"]:::ui
            VAL["Input Validator\n(menu option / task index)"]:::ui
            PRN["Output Formatting / Task Printer\n(lists, status messages)"]:::ui
            ERR["Error Handling\n(invalid option/index, empty lists)"]:::error
        end

        subgraph "Application Layer (Use Cases)"
            DISP["Command Dispatcher / Routing\n(menu selection → handler)"]:::app
            UC_ADD["Add Task"]:::app
            UC_VIEW["View Tasks"]:::app
            UC_DONE["Mark Task as Done"]:::app
            UC_DONE_VIEW["View Completed Tasks"]:::app
            LIFE["Startup/Shutdown Lifecycle\n(load on start, save on exit)"]:::app
        end

        subgraph "Domain Layer"
            TASK["Task Model\n(text + done status)"]:::domain
            TLIST["Task List / Collection"]:::domain
        end

        subgraph "Storage Layer"
            STORE["Task Store\n(in-memory list)"]:::storage
            PERS["Task Persistence Adapter\n(Optional file read/write)"]:::storage
        end
    end

    %% =========================
    %% Context (L0)
    %% =========================
    U -->|"menu_selection/task_text/task_index"| INP
    PRN -->|"menu/task_lists/status_messages"| U

    %% Optional persistence context
    PERS -->|"write_tasks"| FS
    FS -->|"load_tasks"| PERS

    %% =========================
    %% Component interactions (L1)
    %% =========================
    APP -->|"runs_main_loop"| MENU
    APP -->|"runs_main_loop"| INP

    MENU -->|"prompt_user"| INP
    INP -->|"raw_input"| VAL
    VAL -->|"valid_selection"| DISP
    VAL -->|"invalid_input"| ERR
    ERR -->|"error_message"| PRN

    DISP -->|"route_add"| UC_ADD
    DISP -->|"route_view"| UC_VIEW
    DISP -->|"route_mark_done"| UC_DONE
    DISP -->|"route_view_completed"| UC_DONE_VIEW

    %% Use cases to domain/storage
    UC_ADD -->|"create_task"| TASK
    TASK -->|"append"| TLIST
    TLIST -->|"store"| STORE

    UC_VIEW -->|"query_all"| STORE
    STORE -->|"tasks"| UC_VIEW
    UC_VIEW -->|"format_list"| PRN

    UC_DONE -->|"validate_index"| VAL
    UC_DONE -->|"update_done_status"| STORE
    STORE -->|"updated_tasks"| UC_DONE
    UC_DONE -->|"status_message"| PRN

    UC_DONE_VIEW -->|"query_completed"| STORE
    STORE -->|"completed_tasks"| UC_DONE_VIEW
    UC_DONE_VIEW -->|"format_list"| PRN

    %% Lifecycle for optional persistence
    LIFE -->|"load_tasks_on_start"| PERS
    PERS -->|"deserialize"| STORE
    UC_ADD -->|"save_after_mutation"| PERS
    UC_DONE -->|"save_after_mutation"| PERS
    LIFE -->|"save_before_exit"| PERS
    STORE -->|"serialize"| PERS

    %% =========================
    %% Documentation
    %% =========================
    DOC["Usage / Documentation\n(README.md)"]:::doc
    U -.->|"reads_usage"| DOC

    %% =========================
    %% Click Events (paths only)
    %% =========================
    click APP "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click MENU "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click INP "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click VAL "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click PRN "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click ERR "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click DISP "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click UC_ADD "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click UC_VIEW "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click UC_DONE "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click UC_DONE_VIEW "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click TASK "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click TLIST "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click STORE "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click PERS "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click LIFE "https://github.com/zamanayaz/pytodo/blob/main/pytodo-cli.py"
    click DOC "https://github.com/zamanayaz/pytodo/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
    classDef system fill:#1F2937,stroke:#111827,color:#F9FAFB,stroke-width:1px
    classDef ui fill:#DBEAFE,stroke:#2563EB,color:#0F172A,stroke-width:1px
    classDef app fill:#DCFCE7,stroke:#16A34A,color:#052E16,stroke-width:1px
    classDef domain fill:#FEF9C3,stroke:#CA8A04,color:#422006,stroke-width:1px
    classDef storage fill:#FFEDD5,stroke:#F97316,color:#431407,stroke-width:1px
    classDef external fill:#FFE4E6,stroke:#E11D48,color:#4C0519,stroke-width:1px
    classDef error fill:#FEE2E2,stroke:#DC2626,color:#450A0A,stroke-width:1px
    classDef doc fill:#F3E8FF,stroke:#7C3AED,color:#2E1065,stroke-width:1px
```
