# mehdisaraeian/todo-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/mehdisaraeian/todo-bridge
- Repository: https://github.com/mehdisaraeian/todo-bridge

## Overview

##### What this project is (type + purpose)
This is a **Python CLI + library tool** that **converts todo lists** from **CSV** or **Markdown** into a **Super Productivity-compatible JSON backup/import structure**, with an optional **merge mode** that appends into an existing backup while deduplicating projects/tags by name.

So the “system” you’re diagramming is not a distributed runtime with servers; it’s a **local data-processing pipeline**:
- Inputs: CSV/Markdown files (and optionally an existing Super Productivity backup JSON)
- Processing: parsing + normalization + model-building + Super Productivity JSON assembly + merge/dedupe
- Outputs: JSON written to file or stdout, later imported into the **external Super Productivity app**

##### What the file tree says about architecture (mapping code → components)
Key modules (from `src/todo_converter/`):
- `__main__.py`: **CLI entrypoint** (`python -m src.todo_converter ...`)
- `converter.py`: **Main converter interface/orchestrator** (likely `TodoConverter` mentioned in README)
- `base.py`: **Base converter class** / shared behaviors (common parsing, normalization, utilities)
- `csv_converter.py`: CSV-specific parsing + mapping of columns → internal task model
- `markdown_converter.py`: Markdown-specific parsing + hierarchy extraction (headers→projects, indentation→subtasks)
- `models.py`: **Data models** for tasks/projects/tags and/or for Super Productivity JSON entities

Top-level:
- `pyproject.toml`, `requirements.txt`: packaging/deps/build metadata
- `tests/`: unit tests for CSV and Markdown converters (good hints for behavior + edge cases)

Architecturally this is a classic **strategy pattern**:
- `TodoConverter` chooses a concrete converter (CSV/Markdown) and runs a common export pipeline.

**Goal:** show boundaries and external actors.

**Elements**
- **User / Developer** (runs CLI or uses Python API)
- **Todo Converter Tool** (this repo)
- **File System** (reads input CSV/MD; reads optional backup JSON; writes output JSON or stdout)
- **Super Productivity App** (external; user imports JSON output)

- User → Tool: “Run conversion / merge”
- Tool ↔ File System: “Read input”, “Read backup (merge)”, “Write JSON output”
- User → Super Productivity: “Import JSON”
- (Optional) Tool → stdout/pipe: “JSON to stdout for chaining”

**Labeling tips**
- Make it explicit that Super Productivity is **not called via API**; it consumes a JSON file via manual import.

**Goal:** show main runtime blocks: CLI, library, converters, IO.

Even though everything runs in one process, treat major responsibilities as “containers” for clarity:

##### CLI Layer (`__main__.py`)
- parses args: input path, output path (optional), `--merge backup.json`, `--indent`
##### Conversion Orchestrator (`converter.py` / `TodoConverter`)
- detects format (by extension and/or content)
- selects converter strategy
- controls pipeline: parse → normalize → build SP JSON → merge (optional) → serialize
##### Format Converters
- **CSV Converter** (`csv_converter.py`)
- **Markdown Converter** (`markdown_converter.py`)
##### Domain / Data Models (`models.py`)
- task/project/tag representations
- Super Productivity entity structures (ids/entities arrays)
##### Merge + Dedup Logic (likely in `converter.py` and/or `base.py`)
- merge into existing backup JSON
- dedupe projects/tags by name
##### Serialization + Output
- JSON formatting (`indent`)
- write to file or stdout

- CLI → Orchestrator (arguments)
- Orchestrator → Converter (parsed tasks tree)
- Converter → Models (normalized task objects)
- Orchestrator → Merge module (if `--merge`)
- Orchestrator → Serializer → File System/stdout

- Blue: IO boundaries (filesystem/stdout)
- Green: parsing/conversion components (CSV/MD)
- Purple: merge/dedupe
- Gray: models/schema

**Goal:** represent the internal transformation steps as explicit nodes.

##### Input Reader
- Reads CSV/MD text from disk
##### Format Detection
- chooses CSV vs Markdown path
##### Parser
- CSV: header/rows, column mapping (`title`, `notes`, `project`, `tags`, `subtasks`, etc.)
- Markdown: header stack → project assignment, list indentation → hierarchy, checkbox parsing
##### Normalization / Enrichment
- Parse:
- tags: comma-separated or hashtags
- time estimates: “1h”, “30m”, “2h 30m” → milliseconds
- due dates: multiple formats → timestamps
- completion states
- Convert to internal canonical fields
##### Task Tree Builder
- builds parent/child relationships
- ensures `subTaskIds` alignment
##### Super Productivity JSON Builder
- constructs the full required “backup” structure (the README calls out **19 required sections**)
- populates:
- `task.ids` + `task.entities`
- `project` entities
- `tag` entities
- and required empty/default sections (`reminders`, `pluginUserData`, etc.)
##### Merge Mode (optional branch)
- Reads existing backup JSON
- Dedup:
- projects by name
- tags by name
- Appends new tasks without overwriting existing data
##### Serializer
- JSON dumps with indent option
##### Output Writer
- file output OR stdout

**Make the “optional branch” explicit**

##### Relationships / interactions to call out explicitly
- **Strategy selection**: `TodoConverter` → (`CSVConverter` | `MarkdownConverter`)
- **Shared base behavior**: (`CSVConverter`, `MarkdownConverter`) inherit/use `BaseConverter`
- **Models are central**: parsers should output model objects or dicts that later become SP JSON entities
- **No external network dependencies**: all IO is local filesystem + user import step into SP

- “CLI Entrypoint” → `src/todo_converter/__main__.py`
- “Orchestrator / API” → `src/todo_converter/converter.py` (`TodoConverter`)
- “Base Converter” → `src/todo_converter/base.py`
- “CSV Parser/Mapper” → `src/todo_converter/csv_converter.py`
- “Markdown Parser/Hierarchy Extractor” → `src/todo_converter/markdown_converter.py`
- “Models / Schema” → `src/todo_converter/models.py`

Also include:
- “Tests (behavior spec)” → `tests/test_csv_converter.py`, `tests/test_markdown_converter.py`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% Diagram A — System Context
  %% =======================
  subgraph A["Diagram A — System Context"]
    direction TB

    User["User / Developer"]:::actor
    Tool["Todo Converter Tool (Python CLI + Library)"]:::tool
    FS[("Local File System")]:::io
    SP["Super Productivity App (External)"]:::external
    Stdout["Stdout / Pipe"]:::io

    User -->|"run_conversion/merge"| Tool
    Tool -->|"read_input(CSV/MD)"| FS
    Tool -->|"read_backup(optional)"| FS
    Tool -->|"write_output(JSON)"| FS
    Tool -->|"emit_JSON(optional)"| Stdout
    User -->|"manual_import(JSON_backup)"| SP
    FS -->|"JSON_backup_file"| SP
  end

  %% =======================
  %% Diagram B — Local Runtime / Containers
  %% =======================
  subgraph B["Diagram B — Local Runtime (Single Process)"]
    direction TB

    subgraph B1["CLI Layer"]
      direction TB
      CLI["CLI Entrypoint\n(arg parsing, flags: --merge, --indent)"]:::cli
    end

    subgraph B2["Core Library"]
      direction TB
      ORCH["Conversion Orchestrator / Main API\n(TodoConverter: detect, select strategy, control pipeline)"]:::core
      BASE["Base Converter\n(shared parsing/normalization utilities)"]:::base
      MODELS["Domain / Data Models\n(tasks, projects, tags, SP entities)"]:::models
      MERGE["Merge + Dedup Logic\n(additive; dedupe projects/tags by name)"]:::merge
      SER["Serialization + Output\n(JSON dumps, indent option)"]:::serialize
    end

    subgraph B3["Format Converters (Strategy)"]
      direction TB
      CSV["CSV Converter\n(parse rows, map columns → task model)"]:::parser
      MD["Markdown Converter\n(parse headers/indentation → hierarchy)"]:::parser
    end

    subgraph B4["I/O Boundary"]
      direction TB
      INCSV[/"CSV File"/]:::io
      INMD[/"Markdown File"/]:::io
      INBKP[/"Existing SP Backup JSON (optional)"/]:::io
      OUTJSON[/"Output SP Backup JSON"/]:::io
      OUTSTD["stdout (optional)"]:::io
    end

    CLI -->|"args(input,output,merge,indent)"| ORCH
    ORCH -->|"choose_strategy"| CSV
    ORCH -->|"choose_strategy"| MD
    CSV -->|"uses"| BASE
    MD -->|"uses"| BASE
    CSV -->|"emit List[TaskModel]"| MODELS
    MD -->|"emit TaskTree/Tasks"| MODELS
    ORCH -->|"build_entities_from_models"| MODELS
    ORCH -->|"merge_if(--merge)"| MERGE
    MERGE -->|"read/append/dedupe"| MODELS
    ORCH -->|"serialize"| SER
    SER -->|"write_file"| OUTJSON
    SER -->|"write_stdout"| OUTSTD

    INCSV -->|"read_text"| ORCH
    INMD -->|"read_text"| ORCH
    INBKP -->|"read_json(--merge)"| MERGE
  end

  %% =======================
  %% Diagram C — Component-Level Pipeline (Detailed)
  %% =======================
  subgraph C["Diagram C — Detailed Pipeline (Fresh vs Merge)"]
    direction TB

    subgraph C0["Inputs"]
      direction TB
      DEMOCSV[/"demo_tasks.csv"/]:::io
      DEMOMD[/"demo_tasks.md"/]:::io
      BKP[/"backup.json (existing, optional)"/]:::io
    end

    subgraph C1["Fresh Convert (no --merge)"]
      direction TB
      R1["Input Reader"]:::io
      DET1["Format Detection\n(by extension/content)"]:::core
      CSVPATH1["CSV Parse + Column Mapping"]:::parser
      MDPATH1["Markdown Parse + Hierarchy Extraction"]:::parser
      NORM1["Normalization / Enrichment\n(tags, due dates, estimates → ms, completion)"]:::base
      TREE1["Task Tree Builder\n(parent/child, subTaskIds alignment)"]:::core
      BUILD1["Super Productivity JSON Builder\n(backup structure with required sections)"]:::builder
      SER1["Serializer\n(JSON dumps, indent option)"]:::serialize
      W1["Output Writer\n(file or stdout)"]:::io
    end

    subgraph C2["Merge Convert (--merge)"]
      direction TB
      R2["Input Reader"]:::io
      DET2["Format Detection\n(by extension/content)"]:::core
      CSVPATH2["CSV Parse + Column Mapping"]:::parser
      MDPATH2["Markdown Parse + Hierarchy Extraction"]:::parser
      NORM2["Normalization / Enrichment\n(tags, due dates, estimates → ms, completion)"]:::base
      TREE2["Task Tree Builder\n(parent/child, subTaskIds alignment)"]:::core
      NEWENT["Build New SP Entities\n(tasks/projects/tags + required sections)"]:::builder
      GW{"--merge?"}:::gate
      LOAD["Load Existing Backup JSON"]:::merge
      DEDUPE["Merge + Dedup\n(projects/tags by name)\nadditive_only (no overwrites)"]:::merge
      SER2["Serializer\n(JSON dumps, indent option)"]:::serialize
      W2["Output Writer\n(file or stdout)"]:::io
    end

    %% Inputs to readers
    DEMOCSV -->|"CSV_text"| R1
    DEMOMD -->|"MD_text"| R1
    DEMOCSV -->|"CSV_text"| R2
    DEMOMD -->|"MD_text"| R2
    BKP -->|"backup_json"| LOAD

    %% Fresh path connections
    R1 -->|"raw_text"| DET1
    DET1 -->|"route_csv"| CSVPATH1
    DET1 -->|"route_md"| MDPATH1
    CSVPATH1 -->|"parsed_tasks"| NORM1
    MDPATH1 -->|"parsed_tasks_tree"| NORM1
    NORM1 -->|"canonical_tasks"| TREE1
    TREE1 -->|"TaskTree"| BUILD1
    BUILD1 -->|"SP_backup_dict"| SER1
    SER1 -->|"JSON_text"| W1

    %% Merge path connections
    R2 -->|"raw_text"| DET2
    DET2 -->|"route_csv"| CSVPATH2
    DET2 -->|"route_md"| MDPATH2
    CSVPATH2 -->|"parsed_tasks"| NORM2
    MDPATH2 -->|"parsed_tasks_tree"| NORM2
    NORM2 -->|"canonical_tasks"| TREE2
    TREE2 -->|"TaskTree"| NEWENT
    NEWENT -->|"new_entities_dict"| GW
    GW -->|"yes"| LOAD
    LOAD -->|"backup_dict"| DEDUPE
    GW -->|"no"| SER2
    DEDUPE -->|"merged_backup_dict"| SER2
    SER2 -->|"JSON_text"| W2
  end

  %% =======================
  %% Tests + Packaging (supporting artifacts)
  %% =======================
  subgraph D["Supporting Artifacts"]
    direction TB
    TESTCSV["Tests: CSV converter behavior spec"]:::test
    TESTMD["Tests: Markdown converter behavior spec"]:::test
    PYPROJ["Packaging / Dependency Metadata"]:::meta
    REQ["Dependency Pinning (requirements)"]:::meta
  end

  TESTCSV -->|"verifies"| CSV
  TESTMD -->|"verifies"| MD
  PYPROJ -->|"build/packaging_config"| Tool
  REQ -->|"runtime_deps"| Tool

  %% =======================
  %% Click Events (from component mapping)
  %% =======================
  click CLI "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/__main__.py"
  click ORCH "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/converter.py"
  click MERGE "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/converter.py"
  click BASE "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/base.py"
  click CSV "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/csv_converter.py"
  click MD "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/markdown_converter.py"
  click MODELS "https://github.com/mehdisaraeian/todo-bridge/blob/main/src/todo_converter/models.py"
  click TESTCSV "https://github.com/mehdisaraeian/todo-bridge/blob/main/tests/test_csv_converter.py"
  click TESTMD "https://github.com/mehdisaraeian/todo-bridge/blob/main/tests/test_markdown_converter.py"
  click DEMOCSV "https://github.com/mehdisaraeian/todo-bridge/blob/main/demo_tasks.csv"
  click DEMOMD "https://github.com/mehdisaraeian/todo-bridge/blob/main/demo_tasks.md"
  click PYPROJ "https://github.com/mehdisaraeian/todo-bridge/blob/main/pyproject.toml"
  click REQ "https://github.com/mehdisaraeian/todo-bridge/blob/main/requirements.txt"

  %% =======================
  %% Styles
  %% =======================
  classDef actor fill:#F3F4F6,stroke:#374151,color:#111827,stroke-width:1px
  classDef external fill:#FEF3C7,stroke:#B45309,color:#111827,stroke-width:1px
  classDef tool fill:#DBEAFE,stroke:#1D4ED8,color:#111827,stroke-width:1px
  classDef cli fill:#BFDBFE,stroke:#1D4ED8,color:#111827,stroke-width:1px
  classDef core fill:#C7D2FE,stroke:#4338CA,color:#111827,stroke-width:1px
  classDef parser fill:#BBF7D0,stroke:#15803D,color:#111827,stroke-width:1px
  classDef base fill:#A7F3D0,stroke:#047857,color:#111827,stroke-width:1px
  classDef models fill:#E5E7EB,stroke:#4B5563,color:#111827,stroke-width:1px
  classDef builder fill:#DDD6FE,stroke:#6D28D9,color:#111827,stroke-width:1px
  classDef merge fill:#FBCFE8,stroke:#BE185D,color:#111827,stroke-width:1px
  classDef serialize fill:#FED7AA,stroke:#C2410C,color:#111827,stroke-width:1px
  classDef io fill:#E0F2FE,stroke:#0369A1,color:#111827,stroke-width:1px
  classDef gate fill:#FFE4E6,stroke:#9F1239,color:#111827,stroke-width:1px
  classDef test fill:#FDE68A,stroke:#A16207,color:#111827,stroke-width:1px
  classDef meta fill:#F5F5F5,stroke:#6B7280,color:#111827,stroke-width:1px
```
