diff --git a/docs/interfaces.md b/docs/interfaces.md deleted file mode 100644 index 5fab28e..0000000 --- a/docs/interfaces.md +++ /dev/null @@ -1,428 +0,0 @@ -# Mail Manager - Interface Relationships - -This document visualizes all the interfaces in the mail_manager module and their relationships. - -## Overview - -The mail manager uses a hierarchical structure where interfaces are organized by their domain responsibilities: -- **Common Types**: Base types and selectors -- **Providers**: Mail service providers (Gmail, IMAP, etc.) -- **Services**: Individual mail accounts/services -- **Collections**: Mailboxes and folders -- **Messages**: Email messages and their parts - ---- - -## Complete Interface Diagram - -```mermaid -classDiagram - %% Common/Base Types - class SourceSelector { - +string provider - +string service - +string collection - +string message - } - - class ApiRequest~T~ { - +T data - } - - class ApiResponse~T~ { - +T data - +Error error - } - - class ListRange { - +number offset - +number limit - } - - %% Provider Interfaces - class ProviderInterface { - +string @type - +string identifier - +string label - +ProviderCapabilitiesInterface capabilities - } - - class ProviderCapabilitiesInterface { - +boolean ServiceList - +boolean ServiceFetch - +boolean ServiceExtant - +boolean ServiceCreate - +boolean ServiceModify - +boolean ServiceDestroy - +boolean ServiceDiscover - +boolean ServiceTest - } - - class ProviderListRequest { - +SourceSelector sources - } - - class ProviderListResponse { - +ProviderInterface[identifier] providers - } - - class ProviderFetchRequest { - +string identifier - } - - class ProviderFetchResponse { - <> - } - - class ProviderExtantRequest { - +SourceSelector sources - } - - class ProviderExtantResponse { - +boolean[identifier] exists - } - - %% Service Interfaces - class ServiceInterface { - +string @type - +string identifier - +string provider - +string label - +ServiceCapabilitiesInterface capabilities - +object configuration - } - - class ServiceCapabilitiesInterface { - +boolean CollectionList - +boolean CollectionFetch - +boolean CollectionExtant - +boolean CollectionCreate - +boolean CollectionModify - +boolean CollectionDestroy - } - - class ServiceListRequest { - +SourceSelector sources - +ListRange range - } - - class ServiceListResponse { - +ServiceInterface[identifier] services - } - - class ServiceFetchRequest { - +string provider - +string identifier - } - - class ServiceFetchResponse { - <> - } - - class ServiceExtantRequest { - +SourceSelector sources - } - - class ServiceExtantResponse { - +boolean[identifier] exists - } - - class ServiceCreateRequest { - +string provider - +string label - +object configuration - } - - class ServiceCreateResponse { - <> - } - - class ServiceModifyRequest { - +string provider - +string identifier - +string label - +object configuration - } - - class ServiceModifyResponse { - <> - } - - class ServiceDestroyRequest { - +string provider - +string identifier - } - - class ServiceDestroyResponse { - +boolean success - } - - %% Collection Interfaces - class CollectionInterface { - +string @type - +string identifier - +string service - +string provider - +string label - +CollectionCapabilitiesInterface capabilities - +string[] flags - +number messageCount - } - - class CollectionCapabilitiesInterface { - +boolean MessageList - +boolean MessageFetch - +boolean MessageExtant - +boolean MessageCreate - +boolean MessageModify - +boolean MessageDestroy - } - - class CollectionListRequest { - +SourceSelector sources - +ListRange range - } - - class CollectionListResponse { - +CollectionInterface[identifier] collections - } - - class CollectionFetchRequest { - +string provider - +string service - +string identifier - } - - class CollectionFetchResponse { - <> - } - - %% Message Interfaces - class MessageInterface { - +string @type - +string identifier - +string collection - +string service - +string provider - +string[] flags - +Date receivedDate - +Date internalDate - +MessageHeadersInterface headers - +MessagePartInterface[] parts - } - - class MessageHeadersInterface { - +string from - +string[] to - +string[] cc - +string[] bcc - +string subject - +string messageId - +string[] references - +string inReplyTo - +Date date - } - - class MessagePartInterface { - +string partId - +string mimeType - +string filename - +number size - +MessagePartInterface[] subParts - +object headers - +string body - } - - class MessageListRequest { - +SourceSelector sources - +ListRange range - +string[] flags - } - - class MessageListResponse { - +MessageInterface[identifier] messages - } - - class MessageFetchRequest { - +string provider - +string service - +string collection - +string identifier - } - - class MessageFetchResponse { - <> - } - - %% Relationships - ProviderInterface --> ProviderCapabilitiesInterface - ProviderFetchResponse --|> ProviderInterface - ProviderListResponse --> ProviderInterface - - ServiceInterface --> ServiceCapabilitiesInterface - ServiceFetchResponse --|> ServiceInterface - ServiceCreateResponse --|> ServiceInterface - ServiceModifyResponse --|> ServiceInterface - ServiceListResponse --> ServiceInterface - - CollectionInterface --> CollectionCapabilitiesInterface - CollectionFetchResponse --|> CollectionInterface - CollectionListResponse --> CollectionInterface - - MessageInterface --> MessageHeadersInterface - MessageInterface --> MessagePartInterface - MessagePartInterface --> MessagePartInterface : subParts - MessageFetchResponse --|> MessageInterface - MessageListResponse --> MessageInterface - - %% Selector Usage - ProviderListRequest --> SourceSelector - ProviderExtantRequest --> SourceSelector - ServiceListRequest --> SourceSelector - ServiceExtantRequest --> SourceSelector - CollectionListRequest --> SourceSelector - MessageListRequest --> SourceSelector -``` - ---- - -## Hierarchical Structure - -```mermaid -graph TD - A[SourceSelector] --> B[Provider Level] - B --> C[Service Level] - C --> D[Collection Level] - D --> E[Message Level] - - B --> B1[ProviderInterface] - B --> B2[ProviderCapabilities] - - C --> C1[ServiceInterface] - C --> C2[ServiceCapabilities] - - D --> D1[CollectionInterface] - D --> D2[CollectionCapabilities] - - E --> E1[MessageInterface] - E --> E2[MessageHeaders] - E --> E3[MessagePart] -``` - ---- - -## Request/Response Pattern - -All operations follow a consistent request/response pattern: - -```mermaid -sequenceDiagram - participant Client - participant API - participant Provider - - Client->>API: {Operation}Request - API->>Provider: Process Request - Provider->>API: Data - API->>Client: {Operation}Response -``` - -### Operations by Level: - -**Provider Level:** -- List, Fetch, Extant - -**Service Level:** -- List, Fetch, Extant, Create, Modify, Destroy - -**Collection Level:** -- List, Fetch, Extant, Create, Modify, Destroy - -**Message Level:** -- List, Fetch, Extant, Create, Modify, Destroy - ---- - -## Capability Inheritance - -```mermaid -graph LR - A[ProviderCapabilities] -->|enables| B[ServiceCapabilities] - B -->|enables| C[CollectionCapabilities] - C -->|enables| D[Message Operations] -``` - -Capabilities cascade down the hierarchy - if a provider doesn't support `ServiceList`, then no services can be listed for that provider. - ---- - -## Key Patterns - -### 1. **Extends Pattern** -Response interfaces extend their base interface: -- `ProviderFetchResponse extends ProviderInterface` -- `ServiceFetchResponse extends ServiceInterface` - -### 2. **Dictionary Pattern** -List responses use identifier as key: -```typescript -{ - [identifier: string]: Interface -} -``` - -### 3. **SourceSelector Pattern** -Resources are selected hierarchically: -```typescript -{ - provider: "gmail", - service: "user@example.com", - collection: "INBOX", - message: "msg123" -} -``` - -### 4. **Recursive Structure** -MessagePart can contain subParts: -```typescript -MessagePartInterface { - subParts?: MessagePartInterface[] -} -``` - ---- - -## Usage Examples - -### Selecting a specific message: -```typescript -const selector: SourceSelector = { - provider: "gmail", - service: "user@example.com", - collection: "INBOX", - message: "12345" -}; -``` - -### Listing all services for a provider: -```typescript -const request: ServiceListRequest = { - sources: { - provider: "gmail" - }, - range: { - offset: 0, - limit: 50 - } -}; -``` - ---- - -## Interface Files - -- `common.ts` - Base types and selectors -- `provider.ts` - Provider-level interfaces -- `service.ts` - Service-level interfaces -- `collection.ts` - Collection-level interfaces -- `message.ts` - Message-level interfaces