Summary

Create the initial repository structure for shuttle-cli, a Python CLI for automating backup and synchronization of local repositories, cloud drives, Notion tasks, and Chrome bookmarks.

The goal of this issue is only to establish the project architecture, CLI entrypoint, configuration loading, and module organization. No provider implementation is required yet.

Goals

• Use Python 3.12+
• Use a modern package layout
• Support future extension through providers and workflows
• Keep providers as thin adapters
• Keep orchestration logic inside services/workflows
• Separate CLI, business logic, and external APIs

Tech Stack

• Python 3.12+
• typer for CLI
• pydantic for configuration models
• PyYAML for configuration parsing
• pathlib for filesystem operations
• logging for logging

No provider SDKs should be added yet.

Initial folder structure

shuttle-cli/

├── README.md
├── LICENSE
├── .gitignore
├── .env.example
├── pyproject.toml
├── requirements.txt
│
├── config/
│   ├── config.yaml
│   ├── repositories.yaml
│   └── drives.yaml
│
├── data/
│   ├── backups/
│   ├── notion/
│   └── bookmarks/
│
├── scripts/
│   ├── install.sh
│   └── bootstrap.sh
│
└── shuttle/
    ├── __init__.py
    ├── __main__.py
    ├── cli.py
    │
    ├── commands/
    │   ├── backup.py
    │   ├── restore.py
    │   ├── git.py
    │   ├── drives.py
    │   ├── notion.py
    │   └── bookmarks.py
    │
    ├── workflows/
    │   ├── backup.py
    │   └── restore.py
    │
    ├── services/
    │   ├── git_archive.py
    │   ├── drive_sync.py
    │   ├── notion_sync.py
    │   └── bookmark_sync.py
    │
    ├── providers/
    │   ├── github.py
    │   ├── notion.py
    │   ├── chrome.py
    │   ├── google_drive.py
    │   ├── proton_drive.py
    │   ├── icloud_drive.py
    │   └── onedrive.py
    │
    ├── models/
    │   ├── backup.py
    │   ├── bookmark.py
    │   ├── repository.py
    │   └── task.py
    │
    └── utils/
        ├── fs.py
        ├── hashing.py
        ├── logger.py
        ├── retry.py
        ├── yaml.py
        └── zip.py

Architecture

CLI

↓

Command

↓

Workflow / Service

↓

Provider

↓

External API

Providers should never orchestrate multiple operations.

Providers are responsible only for interacting with an external system.

Business logic belongs in services and workflows.

Planned workflows

Backup

repositories

↓

git archive

↓

zip snapshots

↓

upload to configured drives

↓

export notion tasks

↓

export chrome bookmarks

↓

upload exports

Restore

download latest backup

↓

extract archives

↓

restore repositories

↓

import notion

↓

import bookmarks

Planned providers

GitHub

Responsible for repository-related operations.

Future capabilities:

• archive repository
• clone repository
• checkout tag

Google Drive

Future capabilities:

• upload
• download
• list
• delete

OneDrive

Future capabilities:

• upload
• download
• list
• delete

iCloud Drive

Future capabilities:

• upload
• download
• list
• delete

Proton Drive

Future capabilities:

• upload
• download
• list
• delete

Notion

Future capabilities:

• export tasks
• import tasks

Chrome

Future capabilities:

• export bookmarks
• import bookmarks

CLI skeleton

shuttle backup

shuttle restore

shuttle git

shuttle drives

shuttle notion

shuttle bookmarks

Subcommands can be expanded later:

shuttle git backup

shuttle git restore

shuttle notion pull

shuttle notion push

shuttle bookmarks pull

shuttle bookmarks push

shuttle drives upload

shuttle drives download

Configuration example

repositories:

  - ~/engineering
  - ~/private
  - ~/notes

drives:

  google: true
  proton: true
  icloud: true
  onedrive: true

notion:

  database_id: ""

chrome:

  profile: Default

Definition of done

• Repository bootstrapped with the proposed structure
• Python project initializes successfully
• shuttle --help works
• Top-level commands exist as placeholders
• Configuration loader is implemented
• Logging infrastructure exists
• No provider logic implemented yet
• No backup logic implemented yet
• Clear separation between commands, workflows, services, and providers
• Project is ready for incremental implementation of backup features