# amonc/crossword architecture

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

- Interactive diagram: https://gitdiagram.com/amonc/crossword
- Repository: https://github.com/amonc/crossword

## Overview

##### Project type and purpose
- This is a Flutter **UI component library**/plugin that provides an interactive crossword‐puzzle widget (no server or database).
- The README describes a customizable crossword grid, line‐drawing, letter animations and multiple configuration options.

##### File structure
- Top‐level directories:
- `/lib` – core Dart code and components
- `/example` – a full Flutter host app demonstrating the package on all platforms
- `/android`, `/ios`, `/macos`, `/linux`, `/windows`, `/web` – platform integration stubs (GeneratedPluginRegistrant, CMakeLists, Xcode projects)
- Root config: `pubspec.yaml`, CI configs, docs, templates

##### README for architecture hints
- It’s pure Dart/Flutter: no external services, no backend
- Key classes: `Crossword` widget, `CrosswordState`, various `*Decoration` and `*Painter` classes

##### Main components and their relationships
a. **Host Flutter App** (e.g. the `/example` folder)
b. **Crossword Package API** – exposes `Crossword` widget + configuration parameters
c. **Core Widget Layer** (`lib/crossword.dart`)
– Manages state, gesture detection, line tracking, clue logic, callbacks
d. **UI Component Layer** (`lib/components/`)
– `crossword_panel.dart`: renders grid of letters
– `line_painter.dart`: draws user‐drawn lines
– Decoration classes (`letter_pop_decoration.dart`, `reveal_letter_decoration.dart`, etc.) customize animations
e. **Helper Layer** (`lib/helper/extensions.dart`)
– Utility methods (matrix transpose, coordinate conversions, etc.)
f. **Flutter Engine & Platform Plugins**
– On each target (iOS, Android, macOS, Linux, Windows, Web), the package registers itself via `GeneratedPluginRegistrant`.
– No custom platform channels; UI logic runs entirely in Dart/Skia.

##### Architectural patterns
- **Widget + State**: `Crossword` (StatefulWidget) + `CrosswordState` manage UI state and user interactions.
- **CustomPainter** pattern for rendering grid and lines.
- **Decorator** pattern: decoration classes to apply animations and styling.
- **Configuration-driven**: All behavior is parameterized (spacing, hints, animations, allowed directions).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Flow
    hostApp["Host Flutter App"]:::dart
    api["Crossword Package API\n(lib/crossword.dart)"]:::dart
    widget["Crossword StatefulWidget"]:::widget
    state["CrosswordState"]:::widget
    helper["Extensions & Utilities\n(lib/helper/extensions.dart)"]:::dart

    subgraph "UI Components"
        panel["crossword_panel.dart"]:::painter
        painterNode["line_painter.dart"]:::painter
        popDec["letter_pop_decoration.dart"]:::painter
        revealDec["reveal_letter_decoration.dart"]:::painter
        lineDec["line_decoration.dart"]:::painter
        wordLine["word_line.dart"]:::painter
        letterOff["letter_offset.dart"]:::painter
        lineOff["line_offset.dart"]:::painter
    end

    engine["Flutter Engine\n(Skia/Canvas)"]:::platform

    subgraph "Platform Integration Stubs"
        android["Android GeneratedPluginRegistrant.java"]:::platform
        ios_h["iOS GeneratedPluginRegistrant.h"]:::platform
        ios_m["iOS GeneratedPluginRegistrant.m"]:::platform
        ios_xc["iOS Generated.xcconfig"]:::platform
        linux["Linux generated_plugin_registrant.cc"]:::platform
        macosStub["macOS GeneratedPluginRegistrant.swift"]:::platform
        windows["Windows generated_plugin_registrant.cc"]:::platform
        web["Web Stub (example/web/)"]:::platform
    end

    %% Connections
    hostApp -->|"uses widget"| api
    api -->|"instantiates"| widget
    widget -->|"creates"| state
    state -->|"calls utils"| helper
    state -->|"drives"| panel
    state -->|"drives"| painterNode
    state -->|"applies"| popDec
    state -->|"applies"| revealDec
    state -->|"applies"| lineDec
    state -->|"models"| wordLine
    state -->|"uses"| letterOff
    state -->|"uses"| lineOff

    panel -->|"renders on"| engine
    painterNode -->|"renders on"| engine
    popDec -->|"renders on"| engine
    revealDec -->|"renders on"| engine
    lineDec -->|"renders on"| engine
    wordLine -->|"renders on"| engine
    letterOff -->|"renders on"| engine
    lineOff -->|"renders on"| engine

    engine --> android
    engine --> ios_h
    engine --> ios_m
    engine --> ios_xc
    engine --> linux
    engine --> macosStub
    engine --> windows
    engine --> web

    %% Click Events
    click hostApp "https://github.com/amonc/crossword/tree/master/example/"
    click api "https://github.com/amonc/crossword/blob/master/lib/crossword.dart"
    click widget "https://github.com/amonc/crossword/blob/master/lib/crossword.dart"
    click helper "https://github.com/amonc/crossword/blob/master/lib/helper/extensions.dart"
    click panel "https://github.com/amonc/crossword/blob/master/lib/components/crossword_panel.dart"
    click painterNode "https://github.com/amonc/crossword/blob/master/lib/components/line_painter.dart"
    click popDec "https://github.com/amonc/crossword/blob/master/lib/components/letter_pop_decoration.dart"
    click revealDec "https://github.com/amonc/crossword/blob/master/lib/components/reveal_letter_decoration.dart"
    click lineDec "https://github.com/amonc/crossword/blob/master/lib/components/line_decoration.dart"
    click wordLine "https://github.com/amonc/crossword/blob/master/lib/components/word_line.dart"
    click letterOff "https://github.com/amonc/crossword/blob/master/lib/components/letter_offset.dart"
    click lineOff "https://github.com/amonc/crossword/blob/master/lib/components/line_offset.dart"
    click android "https://github.com/amonc/crossword/blob/master/android/app/src/main/java/io/flutter/plugins/GeneratedPluginRegistrant.java"
    click ios_h "https://github.com/amonc/crossword/blob/master/ios/Runner/GeneratedPluginRegistrant.h"
    click ios_m "https://github.com/amonc/crossword/blob/master/ios/Runner/GeneratedPluginRegistrant.m"
    click ios_xc "https://github.com/amonc/crossword/blob/master/ios/Flutter/Generated.xcconfig"
    click linux "https://github.com/amonc/crossword/blob/master/linux/flutter/generated_plugin_registrant.cc"
    click macosStub "https://github.com/amonc/crossword/blob/master/macos/Flutter/GeneratedPluginRegistrant.swift"
    click windows "https://github.com/amonc/crossword/blob/master/windows/flutter/generated_plugin_registrant.cc"
    click web "https://github.com/amonc/crossword/tree/master/web/"

    %% Styles
    classDef dart fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef widget fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef painter fill:#fff9c4,stroke:#f9a825,color:#f57f17;
    classDef platform fill:#e0e0e0,stroke:#424242,color:#424242;
```
