67 lines
4.1 KiB
Markdown
67 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|