# arkalim/kindle-to-notion architecture

> Architecture diagram of the GitHub repository arkalim/kindle-to-notion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arkalim/kindle-to-notion
- Repository: https://github.com/arkalim/kindle-to-notion

## Overview

##### Main Components

a) Input Layer:
- Kindle Device (source of My Clippings.txt)
- GitHub Repository (storage for My Clippings.txt and sync.json)

b) Processing Layer:
- GitHub Actions Runner
- Docker Container (kindle-to-notion)
- Parser Component (represented by src/models/parser.ts)
- Notion Adapter (represented by src/adapters/notion.ts)

c) Storage Layer:
- Notion API/Database (external service)
- Cache Storage (sync.json)

##### Component Relationships

- Data Flow: Kindle → GitHub Repo → Docker Container → Notion API
- Control Flow: GitHub Actions → Docker Container
- Cache Flow: Docker Container ↔ sync.json

##### Architectural Patterns to Highlight

- Adapter Pattern (shown in src/adapters directory)
- Model-View-Controller-like separation (src/models, src/adapters)
- Interface-driven design (src/interfaces directory)

##### Technical Implementation Details

Key elements:
- TypeScript as the primary language
- Docker containerization
- GitHub Actions for automation
- Notion API integration
- File-based caching mechanism

**┌─────────────────────┐**
- Source Layer     │
- [Kindle Device]    │
- ┬───────────┘
- ↓
**┌─────────────────────┐**
- Storage Layer     │
- [GitHub Repo]      │
- ┬───────────┘
- ↓
**┌─────────────────────┐**
- Processing Layer   │
- [Docker Container] │
- Parser         │
- Notion Adapter │
- ┬───────────┘
- ↓
**┌─────────────────────┐**
- Target Layer      │
- [Notion Database]  │
- ┘

- Blue: External services (Notion API)
- Green: Processing components
- Yellow: Storage components
- Gray: Infrastructure components (GitHub Actions, Docker)

Important Elements to Emphasize:
##### The separation of concerns between parsing and API interaction

Additional Considerations:
- Version/environment information
- Security components (API keys, secrets management)
- Where configuration happens (environment variables)

Remember to indicate that this is an automated process triggered by GitHub Actions, which is a crucial architectural decision that enables the seamless synchronization workflow.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Source
        KD[Kindle Device]
        KD --> |My Clippings.txt| GR
    end

    subgraph Repository
        GR[GitHub Repository]
        GHA["GitHub Actions Runner"]:::infra
        SC["sync.json Cache"]:::storage
        GR --> GHA
        GHA <--> SC
    end

    subgraph Processing
        DC["Docker Container"]:::infra
        PC["Parser Component"]:::process
        NA["Notion Adapter"]:::process
        UT["Utility Components"]:::process
        
        GHA --> DC
        DC --> PC
        PC --> NA
        PC <--> UT
        NA <--> UT
    end

    subgraph Target
        NAPI["Notion API"]:::external
        NDB["Notion Database"]:::storage
        NA --> NAPI
        NAPI --> NDB
    end

    subgraph Configuration
        ENV["Environment Config"]:::config
        TSC["TypeScript Config"]:::config
        ENV --> DC
        TSC --> DC
    end

    %% Click Events
    click PC "https://github.com/arkalim/kindle-to-notion/blob/master/src/models/parser.ts"
    click NA "https://github.com/arkalim/kindle-to-notion/blob/master/src/adapters/notion.ts"
    click DC "https://github.com/arkalim/kindle-to-notion/tree/master/Dockerfile"
    click GHA "https://github.com/arkalim/kindle-to-notion/blob/master/.github/workflows/publish.yaml"
    click UT "https://github.com/arkalim/kindle-to-notion/tree/master/src/utils"
    click ENV "https://github.com/arkalim/kindle-to-notion/blob/master/.env.example"
    click TSC "https://github.com/arkalim/kindle-to-notion/blob/master/tsconfig.json"

    %% Styling
    classDef external fill:#87CEEB
    classDef process fill:#90EE90
    classDef storage fill:#FFE4B5
    classDef infra fill:#D3D3D3
    classDef config fill:#DDA0DD

    %% Legend
    subgraph Legend
        E1["External Services"]:::external
        P1["Processing Components"]:::process
        S1["Storage Components"]:::storage
        I1["Infrastructure"]:::infra
        C1["Configuration"]:::config
    end
```
