Twake Mail Refactoring plan

[hoangdat]

Why?

Problem:

• Current architecture has centralized "god object" controller managing multiple concerns, causing tight coupling, difficult testing, and scalability issues.
• Add new feature = touching existing code base

How?

Solution: Introduce Repository Pattern with clear separation between app-level state, feature-level state, and UI controllers.

• App-level state repositories (singleton): Own canonical state, expose streams
  • EmailStateRepository
  • MailboxStateRepository
  • UserStateRepository
  • ...
• Feature-level state: Manage feature-specific state
  • ComposerStateRepository
  • SearchStateRepository
  • ...
• UI controllers: Handle UI events, subscribe to streams
  • MailboxTreeController
  • EmailListController
  • ComposerController
  • ...
• UI reactions

Impact

• Each repository owns one domain (mailbox, email, user)
• Only repository can mutate state
• Controllers subscribe only to what they need
• Controllers read-only via streams
• No controller knows about other controllers

[hoangdat]

Communication pattern

1. Feature-to-feature

Feature A Controller
    ↓ (updates)
App-Level Repository
    ↓ (emits stream)
Feature B Controller (listens)
    ↓ (reacts)
UI Updates

2. Feature-to-app

Feature Controller
    ↓ (updates)
App-Level Repository
    ↓ (persists/broadcasts)
All Features Listening
    ↓ (sync automatically)

3. Within Feature

Feature Controller A
    ↓ (updates)
Feature Repository
    ↓ (emits stream)
Feature Controller B (listens)

[hoangdat]

Example

MailboxController break down

APP-LEVEL REPOSITORY
MailboxRepository

FEATURE-LEVEL REPOSITORY
MailboxRepository
MailboxCreatorRepository
MailboxEditorRepository
MailboxSubscriptionRepository

CONTROLLERS
MailboxActionsController
MailboxTreeController
MailboxSyncController
MailboxNavigationController

VIEWS
MailboxView (composes widgets)

[hoangdat]

Plan

• Integrate Playwright tests from twake-workplace into tmail-flutter
• POC with mailbox controller split first