Skip to content

Latest commit

 

History

History
78 lines (61 loc) · 3.46 KB

AGENTS.md

File metadata and controls

78 lines (61 loc) · 3.46 KB

AGENTS.md

Project Overview

Kanmail is a desktop email client that functions like a kanban board, built with Wails v3 (Go backend + React frontend). It supports Mac, Windows, and Linux.

Architecture Overview

Backend (Go)

Entry Point: main.go creates the Kanmail app and starts the Wails app.

Core Structure (internal/kanmail.go):

  • Kanmail struct holds the Wails app and all services
  • Services are registered with Wails as bound Go methods callable from frontend
  • Circular dependencies are resolved via Bootstrap() pattern

Services (internal/services/):

  • AppService: Application lifecycle, window management, license checking, analytics
  • SettingsService: User settings and configuration persistence
  • AccountsService: Manages email accounts (creates/deletes Account instances)
  • EmailsService: High-level email operations (send, fetch, etc.)
  • ContactsService: Contact management and avatars

Email Implementation (internal/emails/):

  • Account: Represents a single email account with IMAP/SMTP connection pools
  • Folder: Represents an IMAP mailbox with UID tracking and pagination
    • Tracks UIDs from the last 90 days for pagination
    • Uses sparse UID → email cache populated during pagination
    • lastSentUID and lastSentDate track what frontend knows about
  • ConnectionPool: Manages pooled IMAP/SMTP connections (regular, priority, background)
  • imapinterface/: Abstraction layer allowing fake IMAP for testing/screenshots

Key Patterns:

  • Connection pooling for IMAP/SMTP with priority levels
  • UID-based pagination for email folders (folders >1000 emails paginate)
  • Sparse caching with cache invalidation on UID validity changes
  • OAuth2 support with token refresh (see emails/oauth/)
  • Context-based logging with zerolog

Caches (internal/caches/):

  • SQLite-based caching (avatars, contacts, email metadata, folder UIDs, licenses)
  • Single shared caches.db file managed by Caches struct

Types (internal/types/):

  • AccountSettings, FolderName, AccountName, Email and other domain types
  • AccountError for wrapping account-specific errors
  • Event types for frontend communication

Frontend (React + TypeScript)

Build System: Vite with React plugin, TypeScript checking, Babel decorators support

Structure:

  • src/components/: React components organized by feature
    • emails/: Email list, thread, message components
    • settings/: Settings UI components
    • contacts/, send/, license/, etc.
  • src/stores/: State management using custom store pattern
    • base.tsx: BaseStore class with subscription system
    • emails/, settings.ts, contacts.ts, etc.
    • Uses decorator pattern with @subscribe for component subscriptions
  • src/util/: Utility functions
  • src/styles/: LESS stylesheets
  • src/wails/: Auto-generated Wails runtime (DO NOT EDIT MANUALLY)
  • src/bindings/: Auto-generated Go service bindings (DO NOT EDIT MANUALLY)

State Management:

  • Custom store pattern with BaseStore class
  • Components subscribe to stores via subscribe() decorator
  • Stores notify subscribed components on state changes

Important Notes

  • NEVER edit files in frontend/wails/ or frontend/bindings/ - they are auto-generated
  • The project uses a custom fork of go-imap (github.com/oxygem/go-imap/v2) - see replace directive in go.mod
  • Email threading logic in frontend/src/threading.js
  • Connection pools maintain 2 regular + 2 priority + 1 background IMAP connections per account