# z3nz3nn/pa1_slangword architecture

> Architecture diagram of the GitHub repository z3nz3nn/pa1_slangword, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z3nz3nn/pa1_slangword
- Repository: https://github.com/z3nz3nn/pa1_slangword

## Overview

##### Project Type and Purpose
- Desktop Swing application implementing a slang-dictionary with add/edit/delete/search/quiz features.
- Uses file-based data storage (`.txt` and serialized cache), in-memory domain model (Trie), and a GUI layer.

##### File Structure
- Top-level folders:
- data/ (data files: slang lists and cache)
- src/controller/ (business logic and I/O)
- src/model/ (domain models: SlangWord, Trie, TrieNode)
- src/views/ (Swing UI: MainFrame, panels, custom components)
- src/utils/ (helper classes: RandomHelper, SwingUtils)
- src/slang/Main.java (application entry point)
- Pattern: MVC (Model = data structures, Controller = managers + file handlers, View = Swing panels and dialogs)
- Persistence: `FileHandler` reads/writes `slang.txt` and `.ser` cache.

##### README
- Minimal, but confirms project name and purpose (PA01 - Slang Word).

##### Defining Main Components
a. UI Layer (View)
- MainFrame
- MenuBar, ConfirmDialog
- Panels: AddPanel, EditPanel, DeletePanel, SearchPanel, HistoryPanel, RandomPanel, DefinitionPanel, QuizSlangPanel, QuizDefinitionPanel
b. Controller Layer (Business Logic & I/O)
- FileHandler (load/save data)
- SlangManager (CRUD + search + history)
- QuizManager (generate quizzes)
c. Model Layer (Domain)
- SlangWord (POJO for a slang entry)
- Trie & TrieNode (efficient lookup by prefix)
d. Utility Classes
- RandomHelper (randomization logic)
- SwingUtils (common UI helpers)
e. Data Storage
- slang.txt (original data)
- slang_original.txt (backup)
- slang_cache.ser (serialized cached state)

##### Relationships & Data Flow
- Main.java instantiates MainFrame and wires controllers.
- User actions on UI panels → event listeners call Controller methods.
- Controllers interact with Model (update Trie, modify list of SlangWord), possibly via Utilities.
- FileHandler reads/writes files at startup/shutdown or on explicit “save” operations.
- QuizManager uses RandomHelper + Model to prepare quiz questions.
- Controllers push updates back to the View (e.g., refresh a table or show a dialog).

##### Architectural Patterns & Principles
- MVC separation:
View  – Handles user I/O and rendering.
Controller – Orchestrates operations, enforces business rules.
Model – Pure data structures and algorithms (no UI code).
- Single Responsibility: each controller class has a focused role.
- In-memory caching (Trie) for fast searches.
- File-based persistence (no external database).

##### Essential Elements Checklist
- Clear, human-readable labels on all components.
- Call-out notes for any non-obvious utility or caching step.

## Diagram (Mermaid)

```mermaid
graph TB
    %% UI Layer
    subgraph "UI Layer"
        MainFrame["MainFrame"]:::view
        MenuBar["MenuBar"]:::view
        ConfirmDialog["ConfirmDialog"]:::view
        AddPanel["AddPanel"]:::view
        EditPanel["EditPanel"]:::view
        DeletePanel["DeletePanel"]:::view
        SearchPanel["SearchPanel"]:::view
        HistoryPanel["HistoryPanel"]:::view
        RandomPanel["RandomPanel"]:::view
        DefinitionPanel["DefinitionPanel"]:::view
        QuizSlangPanel["QuizSlangPanel"]:::view
        QuizDefinitionPanel["QuizDefinitionPanel"]:::view
    end

    %% Controller Layer
    subgraph "Controller Layer"
        MainApp["Main.java"]:::controller
        FileHandler["FileHandler"]:::controller
        SlangManager["SlangManager"]:::controller
        QuizManager["QuizManager"]:::controller
    end

    %% Model Layer
    subgraph "Model Layer"
        SlangWord["SlangWord"]:::model
        Trie["Trie"]:::model
        TrieNode["TrieNode"]:::model
    end

    %% Utility Layer
    subgraph "Utility"
        RandomHelper["RandomHelper"]:::util
        SwingUtils["SwingUtils"]:::util
    end

    %% Data Storage
    subgraph "Data Storage"
        SlangTxt["slang.txt"]:::storage
        SlangOriginal["slang_original.txt"]:::storage
        SlangCache["slang_cache.ser"]:::storage
    end

    %% Connections
    MainApp -->|"init()/loadSlang()"| FileHandler
    FileHandler -->|"reads"| SlangTxt
    FileHandler -->|"reads"| SlangOriginal
    FileHandler -->|"reads/writes"| SlangCache
    FileHandler -->|"buildTrie()"| Trie
    Trie --> TrieNode
    FileHandler -->|"populateData()"| SlangManager
    MainApp -->|"start()/render()"| MainFrame
    MainFrame --> MenuBar
    MainFrame --> ConfirmDialog
    MainFrame --> AddPanel
    MainFrame --> EditPanel
    MainFrame --> DeletePanel
    MainFrame --> SearchPanel
    MainFrame --> HistoryPanel
    MainFrame --> RandomPanel
    MainFrame --> DefinitionPanel
    MainFrame --> QuizSlangPanel
    MainFrame --> QuizDefinitionPanel
    MainFrame --> SwingUtils
    AddPanel -->|"createSlang()"| SlangManager
    EditPanel -->|"updateSlang()"| SlangManager
    DeletePanel -->|"deleteSlang()"| SlangManager
    SearchPanel -->|"search(query)"| SlangManager
    HistoryPanel -->|"getHistory()"| SlangManager
    RandomPanel -->|"getRandom()"| SlangManager
    DefinitionPanel -->|"lookupDefinition()"| SlangManager
    QuizSlangPanel -->|"generateSlangQuiz()"| QuizManager
    QuizDefinitionPanel -->|"generateDefinitionQuiz()"| QuizManager
    QuizManager --> RandomHelper
    QuizManager --> Trie
    SlangManager --> Trie
    SlangManager --> SlangWord
    SlangManager -->|"saveCache()"| FileHandler
    SlangManager -->|"saveCache()"| SlangCache

    %% Click Events
    click MainApp "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/slang/Main.java"
    click MainFrame "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/MainFrame.java"
    click MenuBar "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/components/MenuBar.java"
    click ConfirmDialog "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/components/ConfirmDialog.java"
    click AddPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/AddPanel.java"
    click EditPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/EditPanel.java"
    click DeletePanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/DeletePanel.java"
    click SearchPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/SearchPanel.java"
    click HistoryPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/HistoryPanel.java"
    click RandomPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/RandomPanel.java"
    click DefinitionPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/DefinitionPanel.java"
    click QuizSlangPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/QuizSlangPanel.java"
    click QuizDefinitionPanel "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/views/panels/QuizDefinitionPanel.java"
    click FileHandler "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/controller/FileHandler.java"
    click SlangManager "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/controller/SlangManager.java"
    click QuizManager "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/controller/QuizManager.java"
    click SlangWord "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/model/SlangWord.java"
    click Trie "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/model/Trie.java"
    click TrieNode "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/model/TrieNode.java"
    click RandomHelper "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/utils/RandomHelper.java"
    click SwingUtils "https://github.com/z3nz3nn/pa1_slangword/blob/master/src/utils/SwingUtils.java"

    %% Styles
    classDef view fill:#D1E8FF,stroke:#3399FF,stroke-width:1px
    classDef controller fill:#D4F8D4,stroke:#33AA33,stroke-width:1px
    classDef model fill:#FFF5B1,stroke:#DDC333,stroke-width:1px
    classDef util fill:#EEEEEE,stroke:#AAAAAA,stroke-width:1px
    classDef storage fill:#CCCCCC,stroke:#888888,stroke-width:1px
```
