# pimutils/vdirsyncer architecture

> Architecture diagram of the GitHub repository pimutils/vdirsyncer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pimutils/vdirsyncer
- Repository: https://github.com/pimutils/vdirsyncer

## Overview

##### Main Components Identification

a. Core Components:
- CLI Interface Layer
- Storage Providers Layer
- Synchronization Engine
- HTTP/DAV Client Layer
- Utility Services

b. Storage Providers:
- DAV (CalDAV/CardDAV)
- Filesystem
- Google
- HTTP
- Memory (for testing)
- SingleFile

**┌─ User Interface Layer ─────────────────┐**
- CLI Commands (discover, sync, repair)  │
- ┤
- Configuration Management            │
- ┘
- ↕
**┌─ Synchronization Layer ───────────────┐**
- Sync Engine                           │
- Status Management                     │
- Meta Sync                            │
- ┘
- ↕
**┌─ Storage Abstraction Layer ──────────┐**
- Base Storage Interface               │
- ┬─────────┬──────────────┤
- DAV Client │ Google  │ Filesystem   │
- (Cal/Card) │ Calendar│ Storage      │
- ┴─────────┴──────────────┘
- ↕
**┌─ External Services Layer ────────────┐**
- CalDAV/CardDAV Servers              │
- Google Calendar API                 │
- Local Filesystem                    │
- ┘

##### Component Details

a. CLI Interface Layer:
- Config parser
- Task executor
- Discovery mechanism
- Parameter fetcher

b. Synchronization Engine:
- Status tracking
- Conflict resolution
- Meta synchronization
- Repair functionality

c. Storage Providers:
- Abstract base storage class
- Implementation-specific adapters
- Authentication handlers

d. External Integrations:
- HTTP client
- SSL/TLS handling
- Authentication methods

##### Additional Elements

- Version compatibility information
- Supported protocols and formats
- Configuration file interaction points

##### Implementation Notes

- The modular architecture allowing multiple storage backends
- The separation between synchronization logic and storage implementations
- The command-line interface structure
- Error handling and recovery mechanisms

Remember to include notes about testing infrastructure and how different components are verified, as evidenced by the extensive test directory structure in the project.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef cli fill:#b3d9ff,stroke:#333,stroke-width:2px
    classDef sync fill:#ffcccc,stroke:#333,stroke-width:2px
    classDef storage fill:#c2f0c2,stroke:#333,stroke-width:2px
    classDef external fill:#ffd9b3,stroke:#333,stroke-width:2px
    classDef utils fill:#e6e6e6,stroke:#333,stroke-width:2px

    %% CLI Interface Layer
    subgraph CLI
        CLI_MAIN["CLI Interface"]
        CONFIG["Config Management"]
        DISCOVER["Discovery Mechanism"]
        PARAMS["Parameter Fetcher"]
        TASKS["Task Executor"]
    end

    %% Synchronization Layer
    subgraph SYNC
        SYNC_ENGINE["Sync Engine"]
        STATUS["Status Management"]
        META["Meta Synchronization"]
        REPAIR["Repair Functionality"]
        SYNC_EX["Sync Exceptions"]
    end

    %% Storage Layer
    subgraph STORAGE
        STORAGE_BASE["Base Storage Interface"]
        DAV["DAV Storage"]
        GOOGLE["Google Calendar"]
        FS["Filesystem Storage"]
        HTTP["HTTP Storage"]
        MEM["Memory Storage"]
        SINGLE["SingleFile Storage"]
    end

    %% External Services Layer
    subgraph EXTERNAL
        CALDAV["CalDAV/CardDAV Servers"]
        GCAL["Google Calendar API"]
        FILESYSTEM["Local Filesystem"]
    end

    %% Utility Services
    subgraph UTILS
        HTTP_CLIENT["HTTP Client"]
        EXCEPTIONS["Exception Handling"]
        VOBJECT["VObject Utilities"]
        GEN_UTILS["General Utilities"]
    end

    %% Relationships
    CLI_MAIN --> CONFIG
    CLI_MAIN --> DISCOVER
    CLI_MAIN --> PARAMS
    CLI_MAIN --> TASKS
    TASKS --> SYNC_ENGINE
    SYNC_ENGINE --> STATUS
    SYNC_ENGINE --> META
    SYNC_ENGINE --> REPAIR
    SYNC_ENGINE --> SYNC_EX
    SYNC_ENGINE --> STORAGE_BASE
    STORAGE_BASE --> DAV
    STORAGE_BASE --> GOOGLE
    STORAGE_BASE --> FS
    STORAGE_BASE --> HTTP
    STORAGE_BASE --> MEM
    STORAGE_BASE --> SINGLE
    DAV --> CALDAV
    GOOGLE --> GCAL
    FS --> FILESYSTEM
    DAV --> HTTP_CLIENT
    HTTP --> HTTP_CLIENT

    %% Click Events
    click CLI_MAIN "https://github.com/pimutils/vdirsyncer/tree/main/vdirsyncer/cli/"
    click CONFIG "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/cli/config.py"
    click DISCOVER "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/cli/discover.py"
    click PARAMS "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/cli/fetchparams.py"
    click TASKS "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/cli/tasks.py"
    click SYNC_ENGINE "https://github.com/pimutils/vdirsyncer/tree/main/vdirsyncer/sync/"
    click STATUS "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/sync/status.py"
    click SYNC_EX "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/sync/exceptions.py"
    click META "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/metasync.py"
    click REPAIR "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/repair.py"
    click STORAGE_BASE "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/base.py"
    click DAV "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/dav.py"
    click FS "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/filesystem.py"
    click GOOGLE "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/google.py"
    click HTTP "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/http.py"
    click MEM "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/memory.py"
    click SINGLE "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/storage/singlefile.py"
    click HTTP_CLIENT "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/http.py"
    click EXCEPTIONS "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/exceptions.py"
    click VOBJECT "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/vobject.py"
    click GEN_UTILS "https://github.com/pimutils/vdirsyncer/blob/main/vdirsyncer/utils.py"

    %% Style Applications
    class CLI_MAIN,CONFIG,DISCOVER,PARAMS,TASKS cli
    class SYNC_ENGINE,STATUS,META,REPAIR,SYNC_EX sync
    class STORAGE_BASE,DAV,GOOGLE,FS,HTTP,MEM,SINGLE storage
    class CALDAV,GCAL,FILESYSTEM external
    class HTTP_CLIENT,EXCEPTIONS,VOBJECT,GEN_UTILS utils
```
