How arkalim/kindle-to-notion works
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.