# eppie-io/eppie-app architecture

> Architecture diagram of the GitHub repository eppie-io/eppie-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eppie-io/eppie-app
- Repository: https://github.com/eppie-io/eppie-app

## Overview

##### Project type and purpose
- Eppie is an open‑source, multi‑platform email client built in C# using the Uno Platform.
- It currently functions as a conventional IMAP/SMTP/Proton Mail client with PGP and seed‑phrase backup, and will later incorporate encrypted p2p networks (IPFS, SBBS).

##### File structure
- Top‑level directories:
- src/Eppie.App – the main solution, includes UI, Shared code, ViewModels, Services, Authorization, and platform‑specific projects.
- src/Tests – unit tests for the ViewModels.
- Architectural pattern: MVVM (Views in Eppie.App.Shared UI, ViewModels in Eppie.App.ViewModels, Services in Eppie.App.Shared/Services).
- Platform targets: UWP, WinAppSDK, WebAssembly, Android, iOS, MacCatalyst, Desktop via Uno.
- Config and CI: .github workflows, Directory.Build.props/targets, global.json.

##### README insights
- Client‑only architecture: no central server.
- Future p2p modules to plug into network/storage layers.
- Uses OAuth2 for Proton authentication, PGP/ECC for encryption, BIP39 for seed phrases.

##### Main components and interactions
a. Components:
- Presentation Layer:
– UI Shared (XAML Views & Controls)
– Platform‑specific UI Hosts (UWP, Uno WASM, Android, iOS, MacCatalyst, Desktop)
- Presentation Logic: ViewModels (Eppie.App.ViewModels)
- Domain/Service Layer:
– Services (AIService, MessageService, FileOperationProvider, LocalSettingsService, AuthorizationProvider/OAuth2, PGP Manager)
- Data Layer:
– Local Encrypted Store (seed‑phrase backup, local database/files)
– Settings and credentials (appsettings.json, LocalSettingsService)
- Network/Protocol Layer:
– IMAP/SMTP client adapters
– Proton OAuth2 module
– Future p2p transports (SBBS) & storage (IPFS)
- External Systems:
– IMAP/SMTP Servers (Gmail, Outlook, Proton)
– Proton Mail API
– (Future) IPFS nodes, SBBS bulletin board

b. Relationships & Data flows:
- UI ←→ ViewModels (two‑way binding)
- ViewModels → Services (async calls)
- Services → Network Layer (protocol adapters) and Data Layer (local store)
- AuthorizationProvider → Token store → Network calls
- PGP Manager ↔ Services (MessageService) for encrypt/decrypt
- AIService ↔ GenAIModel for local AI assistant
- App startup reads appsettings.json → configures services/container

c. Architectural patterns & principles:
- MVVM for UI separation
- Dependency Injection via Directory.Build.props and Uno host
- Modular service abstractions (interfaces in ViewModels.Services and implementations in Shared/Services)
- Platform‑agnostic Shared code, platform projects only supply hosting and native APIs
- Pluggable transport/storage modules

d. Key technologies/frameworks:
- Uno Platform (cross‑platform XAML/C#)
- .NET 6+ with global.json
- OAuth2 module (Eppie.Authorization.OAuth2)
- PGP/ECC via internal utilities
- BIP39 Seed via GenAIModel Utils (temporary)
- CI/CD via GitHub Actions

##### Detailed breakdown
- UI layer subdivided into Shared Controls and Platform Hosts.
- MVVM binding → ViewModels layer.
- Service interfaces vs implementations.
- Data layer: LocalSettingsService, Encrypted Backup.
- Network layer abstraction with current (IMAP/SMTP, Proton OAuth2) and future (P2P transport, decentralized storage).
- AIService and GenAIModel as an ancillary module.
- External dependencies: OAuth2 provider, PGP keys module.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        subgraph "Shared UI" 
            direction TB
            Views["Shared Views & Controls"]:::ui
            StaticRes["StaticResources.xaml"]:::ui
            Converters["Converters & Helpers"]:::ui
        end
        subgraph "Platform Hosts"
            direction TB
            UWP["UWP Host"]:::ui
            WASM["Uno/WASM Host"]:::ui
            Desktop["Desktop Host"]:::ui
            Android["Android Host"]:::ui
            iOS["iOS Host"]:::ui
            MacCatalyst["MacCatalyst Host"]:::ui
            WebAssembly["WebAssembly Host"]:::ui
        end
    end

    %% ViewModels
    ViewModels["ViewModels"]:::vm

    %% Service Layer
    subgraph "Domain/Service Layer"
        direction TB
        subgraph "Shared Services"
            direction TB
            AIService["AIService"]:::service
            MessageService["MessageService"]:::service
            FileOp["FileOperationProvider"]:::service
            LocalSettings["LocalSettingsService"]:::service
            AuthConfig["AuthConfig (abstractions)"]:::service
        end
        subgraph "Platform-specific Services"
            direction TB
            DispApp["DispatcherService (App)"]:::service
            PurchaseApp["PurchaseService (App)"]:::service
            DispUWP["DispatcherService (UWP)"]:::service
            PurchaseUWP["PurchaseService (UWP)"]:::service
        end
    end

    %% Authorization/OAuth2 Module
    AuthModule["Authorization/OAuth2 Module"]:::service
    MailServices["MailServices"]:::service

    %% PGP Management
    subgraph "PGP Management"
        direction TB
        PgpKeyView["PgpKeyPage View"]:::service
        PgpKeysView["PgpKeysPage View"]:::service
        PgpKeyVM["PgpKeyPageViewModel"]:::service
        PgpKeysVM["PgpKeysPageViewModel"]:::service
    end

    %% AI & GenAIModel
    AIImpl["AI Service Implementation"]:::service
    GenAI["GenAIModel & Helpers"]:::service

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        AppSettings["appsettings.json"]:::data
        LocalStore["Encrypted Local Store"]:::data
    end

    %% Network Layer
    subgraph "Network/Protocol Layer"
        direction TB
        IMAP["IMAP/SMTP Adapters"]:::network
        OAuth2Mod["OAuth2 Module"]:::network
        FutureP2P["Future P2P Transports"]:::network
        FutureStorage["Future Storage (IPFS)"]:::network
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        IMAPServers["IMAP/SMTP Servers"]:::external
        ProtonAPI["Proton Mail API"]:::external
        IPFSNodes["IPFS Nodes"]:::external
        SBBS["SBBS Bulletin Board"]:::external
    end

    %% Connections
    UWP -->|hosts| Views
    WASM -->|hosts| Views
    Desktop -->|hosts| Views
    Android -->|hosts| Views
    iOS -->|hosts| Views
    MacCatalyst -->|hosts| Views
    WebAssembly -->|hosts| Views

    Views <-->|data binding| ViewModels
    StaticRes --> ViewModels
    Converters --> ViewModels

    ViewModels -->|calls| AIService
    ViewModels -->|calls| MessageService
    ViewModels -->|calls| FileOp
    ViewModels -->|calls| LocalSettings
    ViewModels -->|uses| AuthConfig

    AIService --> AIImpl
    AIService --> GenAI

    MessageService -->|encrypt/decrypt| PgpKeyView
    MessageService -->|encrypt/decrypt| PgpKeysView

    DispApp -->|platform services| ViewModels
    PurchaseApp --> ViewModels
    DispUWP --> ViewModels
    PurchaseUWP --> ViewModels

    AuthConfig -->|implements| AuthModule
    AuthModule --> MailServices

    LocalSettings --> AppSettings
    LocalSettings --> LocalStore
    FileOp --> LocalStore

    AIImpl --> GenAI
    GenAI -->|utils| AIImpl

    MessageService --> IMAP
    MailServices --> OAuth2Mod
    AuthModule --> OAuth2Mod

    IMAP --> IMAPServers
    OAuth2Mod --> ProtonAPI
    FutureP2P --> SBBS
    FutureStorage --> IPFSNodes

    %% Click Events
    click Views "https://github.com/eppie-io/eppie-app/tree/main/src/Eppie.App/Eppie.App.Shared/Views"
    click StaticRes "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/StaticResources/StaticResources.xaml"
    click Converters "https://github.com/eppie-io/eppie-app/tree/main/src/Eppie.App/Eppie.App.Shared/Converters"
    click Converters "https://github.com/eppie-io/eppie-app/tree/main/src/Eppie.App/Eppie.App.Shared/Helpers"
    click UWP "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.UWP"
    click WASM "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.UI.Uno"
    click Desktop "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Platforms/Desktop/Program.cs"
    click Android "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Platforms/Android/MainActivity.Android.cs"
    click iOS "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Platforms/iOS/Main.iOS.cs"
    click MacCatalyst "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Platforms/MacCatalyst/Main.maccatalyst.cs"
    click WebAssembly "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Platforms/WebAssembly/Program.cs"
    click ViewModels "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.ViewModels"
    click AIService "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Services/AIService.cs"
    click MessageService "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Services/MessageService.cs"
    click FileOp "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Services/FileOperationProvider.cs"
    click LocalSettings "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Services/LocalSettingsService.cs"
    click AuthConfig "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Authorization/AuthConfig.cs"
    click DispUWP "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.UWP/Services/DispatcherService.cs"
    click PurchaseUWP "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.UWP/Services/PurchaseService.cs"
    click DispApp "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Services/DispatcherService.cs"
    click PurchaseApp "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/Services/PurchaseService.cs"
    click AuthModule "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.Authorization.OAuth2/AuthorizationProvider.cs"
    click MailServices "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.Authorization.OAuth2/MailServices.cs"
    click PgpKeyView "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Views/PgpKeyPage.xaml"
    click PgpKeysView "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.Shared/Views/PgpKeysPage.xaml"
    click PgpKeyVM "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.ViewModels/PgpKeyPageViewModel.cs"
    click PgpKeysVM "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App.ViewModels/PgpKeysPageViewModel.cs"
    click AIImpl "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.AI/Service.cs"
    click GenAI "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.AI/Utils/GenAIModel.cs"
    click AppSettings "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.App/appsettings.json"
    click Directory.Build.props "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Directory.Build.props"
    click Directory.Build.targets "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Directory.Build.targets"
    click IMAPServers "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.Authorization.OAuth2/TokenRefresher.cs"
    click OAuth2Mod "https://github.com/eppie-io/eppie-app/blob/main/src/Eppie.App/Eppie.Authorization.OAuth2/AuthorizationFactory.cs"
    click IPFSNodes "https://github.com/eppie-io/eppie-app/blob/main/src/Tests/Eppie.App.ViewModels.Tests"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6
    classDef vm fill:#D0E8FF,stroke:#0366d6
    classDef service fill:#DFF5D8,stroke:#228B22
    classDef network fill:#FFE5B4,stroke:#FF8C00
    classDef data fill:#F0F0F0,stroke:#999999
    classDef external fill:#E8E8E8,stroke:#666666
```
