# 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.