improvements

architecture/dialogue_system_architecture.md

@@ -0,0 +1,93 @@
+# Dialogue System Architecture
+
+```mermaid
+graph TD
+    A[Base Character Scene] --> B(DialogueSystem)
+    B --> C(DialogueBox UI)
+    B --> D(TextRevealer)
+    B --> E(AnimationController)
+    B --> F(Timer)
+    
+    C --> G[Visual Display]
+    D --> H[Character-by-Character Reveal]
+    E --> I[Show/Hide Animations]
+    F --> J[Duration Management]
+    
+    subgraph "Dialogue Flow"
+        B --> K{Trigger Dialogue}
+        K -->|Text + Duration| L[Show Dialogue Box]
+        L --> M[Start Text Reveal]
+        M --> N[Wait for Duration]
+        N --> O[Hide Dialogue Box]
+    end
+    
+    subgraph "Components"
+        C --> C1[White Background]
+        C --> C2[Positioning]
+        D --> D1[Character Timing]
+        D --> D2[Text Display]
+        E --> E1[Animation Playback]
+        F --> F1[Timer Management]
+    end
+    
+    style A fill:#e1f5fe
+    style B fill:#f3e5f5
+    style C fill:#e8f5e9
+    style D fill:#fff3e0
+    style E fill:#fce4ec
+    style F fill:#f1f8e9
+```
+
+## Component Descriptions
+
+### Base Character Scene (A)
+- Contains the character sprite (Polygon2D)
+- Acts as the entry point for dialogue triggering
+- Manages the dialogue system interface
+
+### DialogueSystem (B) - Main Controller
+- Coordinates all dialogue functionality
+- Interfaces with UI components
+- Handles timing and state management
+- Provides public API for triggering dialogue
+
+### DialogueBox UI (C)
+- Visual representation of dialogue
+- White background container
+- Proper positioning relative to character
+- Handles visibility states
+
+### TextRevealer (D)
+- Manages character-by-character text display
+- Controls reveal timing
+- Updates text label content incrementally
+- Handles text formatting and wrapping
+
+### AnimationController (E)
+- Manages show/hide animations
+- Controls timing of UI transitions
+- Ensures smooth visual experience
+- Handles animation cleanup
+
+### Timer (F)
+- Manages dialogue duration
+- Triggers automatic closure
+- Provides timing feedback to system
+- Handles edge cases (zero/negative durations)
+
+## Flow Description
+
+1. **Trigger**: Base character calls `trigger_dialogue(text, duration)`
+2. **Show**: DialogueSystem initiates show animation for DialogueBox
+3. **Reveal**: TextRevealer starts character-by-character text display
+4. **Wait**: Timer waits for specified duration
+5. **Hide**: AnimationController triggers hide animation
+6. **Complete**: System returns to idle state
+
+## Integration Points
+
+- Base Character Scene: Public API interface
+- DialogueBox UI: Visual rendering component  
+- TextRevealer: Text animation logic
+- AnimationController: UI transition handling
+- Timer: Duration management