How mehdisaraeian/todo-bridge works
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