pyLyricFlow/docs/architecture.md

System Architecture

LyricFlow is built using Python 3 and the PyQt6 framework. The codebase follows a strict separation of concerns between the linguistic engine and the user interface.

Directory Structure

lyricflow/
├── docs/               # Technical documentation
├── src/
│   ├── engine/         # Linguistic logic (Rhymes, Phonetics, Syllables)
│   ├── gui/            # UI components and styling
│   │   └── components/ # Specialized widgets (Editor, Explorer, Sidebar)
│   ├── lyricflow_core/ # Shared core for desktop/mobile clients
│   │   ├── api/        # Stable service/facade APIs
│   │   ├── engine/     # Core linguistic implementation
│   │   └── storage/    # Core persistence implementation
│   └── utils/          # Legacy compatibility wrappers
├── run.py              # Main entry point script
└── README.md           # Project overview

Module Responsibilities

src/engine

• phonetics.py: Wraps nltk.cmudict. Handles word normalization and phonetic extraction. Contains the PhoneticProcessor singleton.
• rhyme_engine.py: The core logic. Indexes the phonetic dictionary into memory for O(1) slant/perfect rhyme lookup. Implements word association (synonyms/vibes) using NLTK WordNet. These now proxy to src/lyricflow_core/engine for backward compatibility.

src/lyricflow_core

• api/analysis.py: Stable analysis service used by GUI and future mobile clients.
• api/project_state.py: Stable project state read/write and defensive parsing.
• api/facade.py: Aggregated LyricFlowCoreFacade integration point.
• engine/ and storage/: Canonical implementation modules shared across clients.

src/gui

• main_window.py: The central orchestrator.
  • Manages the QSplitter layout.
  • Handles Tab Management for multi-file editing.
  • Implements Project Persistence via .lyricproject JSON files.
  • Manages app-level restore and preferences via QSettings and recovered session snapshots.
• components/explorer.py: Uses QFileSystemModel and QTreeView to provide an IDE-like project explorer with context menu file operations.
• components/editor.py: A specialized QPlainTextEdit implementing:
  • RhymeHighlighter: Real-time coloring based on flow density and LyricDown syntax.
  • Syllable Margin: Custom painting to show the meter of each line.
  • Debounced Analysis: Performance-optimized logic to prevent UI lag.
• components/sidebar.py: A composite widget that displays dynamic lists of rhymes, synonyms, and vibe concepts based on the current cursor selection.
• components/preferences_dialog.py: Modal preferences UI for startup/session defaults and appearance toggles.

src/utils

• app_settings.py: Defines AppPreferences and AppSettingsStore, persisting app-level behavior and UI chrome state through QSettings.
• session_store.py: Stores and restores recovered unsaved tabs (untitled and dirty files) under app data as JSON snapshots.

Data Flow

1. User Types: LyricEditor detects change -> Reset Debounce Timer.
2. Timer Expires: LyricEditor calls engine.get_rhyme_groups().
3. Highlighter Updates: RhymeHighlighter receives results and colors the text, while strictly excluding LyricDown keywords/comments.
4. Project Save: MainWindow writes .lyricproject with open files, active file, and cursor positions.
5. Session Autosave: Every 30s (and on close), unsaved tabs are captured to app data for crash/quit recovery.
6. Startup Restore: Preferences are loaded first, then last project and recovered snapshots are optionally restored.
7. Selection: User clicks a word -> wordSelected signal sent to Sidebar -> Sidebar fetches creative suggestions from the engine.

Styling

The application uses a custom CSS-like dictionary approach within PyQt to implement a Dracula Theme. This theme is consistently applied to the menu bar, tabs, explorer, editor, and sidebar to ensure a premium look and feel.