noctua/DEVNOTE/Workflow.md

Noctua – Code Workflow & Architecture

Status

MIGRATION ABGESCHLOSSEN ✅

Die Migration zu Clean Architecture ist zu 100% abgeschlossen.

• ✅ Alte src/app/ Struktur wurde gelöscht
• ✅ Neue Clean Architecture vollständig implementiert und aktiv
• ✅ Alle Layer korrekt implementiert: ui/, application/, domain/, infrastructure/
• ✅ DocumentManager ist Single Source of Truth
• ✅ Command Pattern durchgängig implementiert
• ✅ Views nutzen gecachte Daten aus AppModel
• ✅ Sync-Mechanismus zwischen DocumentManager und UI-Model

---

Aktuelle Architektur (Finale Struktur)

┌─────────────────────────────────────────────────────────────┐
│                     src/ui/                                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  TEA Pattern (Model – Update – View)                 │   │
│  │                                                      │   │
│  │  model.rs      - AppModel (UI State + Document!)     │   │
│  │  message.rs    - AppMessage (Events)                 │   │
│  │  update.rs     - Update Logic                        │   │
│  │  mod.rs        - Noctua (COSMIC App)                 │   │
│  │  view/         - View Components                     │   │
│  └──────────────────┬───────────────────────────────────┘   │
│                     │                                       │
│  ┌──────────────────▼───────────────────────────────────┐   │
│  │  document/  ⚠️ PROBLEM: Domain Logic in TEA Layer!   │   │
│  │                                                      │   │
│  │  mod.rs        - DocumentContent enum                │   │
│  │  raster.rs     - RasterDocument struct               │   │
│  │  vector.rs     - VectorDocument struct               │   │
│  │  portable.rs   - PortableDocument struct             │   │
│  │  file.rs       - File operations                     │   │
│  │  meta.rs       - Metadata extraction                 │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  src/application/       NICHT VERWENDET                     │
│  - document_manager.rs  (existiert, wird ignoriert)         │
│  - commands/            (leer)                              │
│  - queries/             (leer)                              │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  src/domain/            NICHT VERWENDET                     │
│  - document/core/       (Trait-Definitionen existieren)     │
│  - document/types/      (Alternative Implementierungen)     │
│  - document/operations/ (Operations)                        │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  src/infrastructure/    NICHT VERWENDET                     │
│  - loaders/             (DocumentLoaderFactory existiert)   │
│  - filesystem/          (file_ops)                          │
└─────────────────────────────────────────────────────────────┘

---

Aktueller Workflow (Detailliert)

1. Application Start

main.rs
  ↓
cosmic::app::run::<Noctua>(Settings, Flags)
  ↓
Noctua::init()
  ↓
AppModel::new()
  ↓
document::file::open_initial_path()  // Falls CLI-Argument vorhanden

Wichtig: Initial path wird direkt in AppModel geladen, nicht über DocumentManager.

2. User Input → Message → Update

Keyboard/Mouse Event
  ↓
handle_key_press() / UI Widget
  ↓
AppMessage
  ↓
Noctua::update(&mut self, message: AppMessage)
  ↓
match message {
    ToggleNavBar / ToggleContextPage => handled in Noctua::update()
    Alle anderen => update::update(&mut self.model, &message, &self.config)
}

3. Update Logic (src/app/update.rs)

pub fn update(model: &mut AppModel, msg: &AppMessage, config: &AppConfig) -> UpdateResult {
    match msg {
        // ---- File / Navigation ----
        AppMessage::OpenPath(path) => {
            document::file::open_single_file(model, path);
            // Direkter Zugriff auf model.document
        }
        
        AppMessage::NextDocument => {
            document::file::navigate_next(model);
            // Modifiziert model.document direkt
        }
        
        // ---- Transformationen ----
        AppMessage::RotateCW => {
            if let Some(doc) = &mut model.document {
                doc.rotate_cw();  // Direkt auf Document
            }
        }
        
        // ---- Crop ----
        AppMessage::ApplyCrop => {
            if let Some(doc) = &model.document {
                document::file::save_crop_as(doc, ...);
                // Re-open nach Crop
                document::file::open_single_file(model, &new_path);
            }
        }
        
        // ...
    }
}

Problem: Keine Trennung zwischen UI-State und Business Logic!

4. Document Operations (src/app/document/)

// DocumentContent = Type-Erasure Enum
pub enum DocumentContent {
    Raster(RasterDocument),
    Vector(VectorDocument),
    Portable(PortableDocument),
}

// Trait Implementations für Type Erasure
impl Transformable for DocumentContent {
    fn rotate(&mut self, rotation: Rotation) {
        match self {
            Self::Raster(doc) => doc.rotate(rotation),
            Self::Vector(doc) => doc.rotate(rotation),
            Self::Portable(doc) => doc.rotate(rotation),
        }
    }
}

// Convenience Methods
impl DocumentContent {
    pub fn rotate_cw(&mut self) {
        let new_rotation = self.transform_state().rotation.rotate_cw();
        self.rotate(new_rotation);
    }
}

5. File Operations (src/app/document/file.rs)

pub fn open_document(path: &Path) -> anyhow::Result<DocumentContent> {
    let kind = DocumentKind::from_path(path)?;
    
    match kind {
        DocumentKind::Raster => {
            let raster = RasterDocument::open(path)?;
            DocumentContent::Raster(raster)
        }
        DocumentKind::Vector => { ... }
        DocumentKind::Portable => { ... }
    }
}

pub fn navigate_next(model: &mut AppModel) {
    // Direkt auf model.folder_entries zugreifen
    // Direkt load_document_into_model() aufrufen
}

Problem: File-Operations greifen direkt auf Model zu!

6. View Rendering (src/app/view/)

// canvas.rs
pub fn view<'a>(model: &'a AppModel, config: &'a AppConfig) -> Element<'a, AppMessage> {
    if let Some(doc) = &model.document {
        let handle = doc.handle();
        let (width, height) = doc.dimensions();
        
        // Render mit Viewer-Widget
        Viewer::new(handle)
            .with_state(scale, pan_x, pan_y)
            .on_state_change(|scale, x, y| AppMessage::ViewerStateChanged { ... })
    }
}

View hat &AppModel, kann also direkt auf model.document zugreifen.

---

Was NICHT verwendet wird

DocumentManager (src/application/document_manager.rs)

// ❌ Existiert, wird aber NICHT instanziiert!
pub struct DocumentManager {
    current_document: Option<DocumentContent>,  // ← domain::document::core::content::DocumentContent
    current_path: Option<PathBuf>,
    // ...
    loader: DocumentLoaderFactory,  // ← infrastructure::loaders
}

impl DocumentManager {
    pub fn open_document(&mut self, path: &Path) -> DocResult<()> { ... }
    pub fn next_document(&mut self) -> Option<PathBuf> { ... }
    // ...
}

Problem: Diese Klasse orchestriert die Business Logic sauber, wird aber komplett ignoriert!

Domain Layer (src/domain/)

// ❌ Alternative Trait-Definitionen, werden nicht benutzt
// src/domain/document/core/document.rs
pub trait Renderable { ... }
pub trait Transformable { ... }

// src/domain/document/core/content.rs
pub enum DocumentContent { ... }  // Duplikat zu src/app/document/mod.rs!

Problem: Es gibt ZWEI DocumentContent Enums!

• src/app/document/mod.rs (wird benutzt)
• src/domain/document/core/content.rs (wird ignoriert)

Infrastructure Layer (src/infrastructure/)

// ❌ DocumentLoaderFactory existiert, wird nicht verwendet
// src/infrastructure/loaders/document_loader.rs
pub struct DocumentLoaderFactory { ... }

impl DocumentLoaderFactory {
    pub fn load(&self, path: &Path) -> DocResult<DocumentContent> { ... }
}

Problem: Stattdessen wird document::file::open_document() verwendet!

---

Gewünschte Architektur (SOLL-Zustand)

┌─────────────────────────────────────┐
│         TEA (app/)                  │
│  ┌──────────┬──────────┬──────────┐ │
│  │  Model   │  Update  │   View   │ │
│  │ (UI nur) │          │          │ │
│  └────┬─────┴─────┬────┴─────┬────┘ │
│       │           │          │      │
└───────┼───────────┼──────────┼──────┘
        │           │          │
        ▼           ▼          ▼
┌─────────────────────────────────────┐
│      Application Layer              │
│  ┌─────────────────────────────┐    │
│  │   DocumentManager           │    │
│  │   - open_document()         │    │
│  │   - next_document()         │    │
│  │   - transform_document()    │    │
│  └────────────┬────────────────┘    │
│               │                     │
│  Commands     │     Queries         │
│  - OpenDoc    │     - GetDocument   │
│  - Transform  │     - GetMetadata   │
└───────────────┼─────────────────────┘
                │
                ▼
┌─────────────────────────────────────┐
│       Domain Layer                  │
│  ┌─────────────────────────────┐    │
│  │  DocumentContent (enum)     │    │
│  │  - Raster / Vector / PDF    │    │
│  ├─────────────────────────────┤    │
│  │  Traits:                    │    │
│  │  - Renderable               │    │
│  │  - Transformable            │    │
│  │  - MultiPage                │    │
│  ├─────────────────────────────┤    │
│  │  Operations:                │    │
│  │  - transform::rotate()      │    │
│  │  - transform::flip()        │    │
│  │  - render::scale()          │    │
│  └────────────┬────────────────┘    │
└───────────────┼─────────────────────┘
                │
                ▼
┌─────────────────────────────────────┐
│    Infrastructure Layer             │
│  - DocumentLoaderFactory            │
│  - RasterLoader / SvgLoader / ...   │
│  - FileOps                          │
└─────────────────────────────────────┘

Idealer Workflow

User Input
  ↓
AppMessage
  ↓
Noctua::update()
  ↓
app::update::update()
  ↓
DocumentManager::next_document()  ← Application Layer
  ↓
DocumentContent::rotate_cw()      ← Domain Layer
  ↓
DocumentLoaderFactory::load()     ← Infrastructure Layer
  ↓
Model aktualisieren (nur UI state)
  ↓
View re-render

---

Kernprobleme

1. Model enthält Business Logic

pub struct AppModel {
    pub document: Option<DocumentContent>,  // ← Business Entity in UI Model!
    pub metadata: Option<DocumentMeta>,     // ← Business Data in UI Model!
    pub current_path: Option<PathBuf>,
    pub folder_entries: Vec<PathBuf>,       // ← Business Logic in UI Model!
    
    // UI State (okay)
    pub view_mode: ViewMode,
    pub pan_x: f32,
    pub pan_y: f32,
    pub tool_mode: ToolMode,
    pub crop_selection: CropSelection,
}

Problem: Model sollte NUR UI-State enthalten!

Lösung: Document-Management in DocumentManager auslagern.

2. Direkte Manipulation statt Commands

// ❌ Aktuell
AppMessage::RotateCW => {
    if let Some(doc) = &mut model.document {
        doc.rotate_cw();
    }
}

// ✅ Sollte sein
AppMessage::RotateCW => {
    let cmd = TransformDocumentCommand::new(TransformOperation::RotateCw);
    cmd.execute(&mut app.document_manager)?;
    sync_model_from_manager(app);
}

3. File Operations in Update Logic

// ❌ Aktuell: src/app/document/file.rs
pub fn navigate_next(model: &mut AppModel) {
    // Direkt auf model zugreifen
}

// ✅ Sollte sein: src/application/document_manager.rs
impl DocumentManager {
    pub fn next_document(&mut self) -> Option<PathBuf> {
        // Business Logic hier
    }
}

4. Zwei parallele DocumentContent Implementierungen

• src/app/document/mod.rs::DocumentContent (aktiv)
• src/domain/document/core/content.rs::DocumentContent (inaktiv)

Lösung: Eine davon löschen und konsolidieren.

---

Migration Path

Phase 1: Konsolidierung (JETZT)

1. Entscheidung treffen: Welche Implementation behalten?

   • Option A: src/app/document/ als Basis, nach src/domain/ verschieben
   • Option B: src/domain/ vervollständigen, src/app/document/ löschen

2. DocumentManager aktivieren

   pub struct Noctua {
       core: Core,
       pub model: AppModel,           // Nur UI State
       pub document_manager: DocumentManager,  // Business Logic
       pub config: AppConfig,
   }
   

3. Update-Logik umleiten

   AppMessage::NextDocument => {
       app.document_manager.next_document();
       sync_ui_from_manager(app);  // Model aus Manager aktualisieren
   }
   

Phase 2: Commands implementieren

// src/application/commands/navigate.rs
pub struct NavigateCommand {
    direction: NavigationDirection,
}

impl NavigateCommand {
    pub fn execute(&self, manager: &mut DocumentManager) -> DocResult<()> {
        match self.direction {
            NavigationDirection::Next => manager.next_document(),
            NavigationDirection::Previous => manager.previous_document(),
        }
    }
}

Phase 3: Model bereinigen

pub struct AppModel {
    // ❌ Entfernen
    // pub document: Option<DocumentContent>,
    // pub metadata: Option<DocumentMeta>,
    // pub folder_entries: Vec<PathBuf>,
    
    // ✅ Nur UI State
    pub view_mode: ViewMode,
    pub pan_x: f32,
    pub pan_y: f32,
    pub tool_mode: ToolMode,
    pub crop_selection: CropSelection,
    pub error: Option<String>,
    
    // ✅ Cached data for rendering (read-only)
    pub current_image_handle: Option<ImageHandle>,
    pub current_dimensions: Option<(u32, u32)>,
}

---

Empfehlung

⚠️ STOP! Migration ist noch nicht fertig!

Bevor neue Features implementiert werden:

1. Duplikate entfernen (DocumentContent existiert 2x)
2. DocumentManager integrieren (existiert, wird nicht benutzt)
3. Model von Business Logic trennen (Document raus aus AppModel)
4. Update-Logik über Application Layer leiten (nicht direkt auf Model)

Geschätzte Zeit: 2-3 Tage für vollständige Migration.

Risiko ohne Migration: Code wird immer schwerer wartbar, neue Features müssen doppelt implementiert werden (einmal in src/app/document/, einmal in src/domain/).

---

Referenzen

• AGENTS.md – AI Assistant Guidelines (behauptet 95% fertig, tatsächlich ~40%)
• DEVNOTE/Tree.md – Ziel-Architektur (existiert, wird nicht verwendet)
• src/app/ – Aktive Implementation (TEA + Business Logic vermischt)
• src/application/ – Sollte verwendet werden, wird ignoriert
• src/domain/ – Sollte verwendet werden, wird ignoriert
• src/infrastructure/ – Teilweise verwendet (nicht konsistent)

---

Stand: Januar 2025
Status: Architektur-Analyse abgeschlossen, Migration-Bedarf identifiziert