# quangthangit/vocab-korea architecture

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

- Interactive diagram: https://gitdiagram.com/quangthangit/vocab-korea
- Repository: https://github.com/quangthangit/vocab-korea

## Overview

##### Project Type & Purpose
- This is a Flutter-based cross-platform mobile application (with support for Android, iOS, and even a basic web implementation) meant to handle vocabulary learning.
- The project includes several screens/pages that deal with learning features such as flashcards, vocabulary games, study essays, and similar interactive learning experiences. It also incorporates algorithmic modules (e.g., Levenshtein, random vocabulary, etc.) to support its vocabulary operations.

##### Analyzing the File Structure
- Platform Directories: The top-level directories “android”, “ios”, and “web” define the native configurations and platform-specific requirements. These indicate that while your application is written in Flutter (under the “lib” folder), it must interface with native APIs and handle different deployment environments.
- Application Code (lib):
- "lib/pages": This contains UI screens (like LoginPage, HomePage, FlashCardPage, etc.) that form the View layer.
- "lib/components" and "lib/widget": These hold reusable UI components (such as bars for navigation, flashcard views, bottom sheets) that build up more complex views.
- "lib/models": Holds data models describing entities such as User, Lesson, Vocabulary, which are used by the UI and service layers.
- "lib/services", "lib/api", and "lib/serviceoffline": These directories include business logic, API integrations (for tasks like vocabulary generation and translation), offline handling, and calls to services. They bridge between the UI and data models.
- "lib/Algorithm": Contains modules for performing specific algorithmic tasks – for instance, text similarity (Levenshtein), randomizing vocabulary, and processing study essays.

##### Key Architectural Components
a. UI Layer:
- Composed of pages (screens) and subcomponents.
- Handles user interaction and presentation logic.
b. Business Logic / Service Layer:
- Houses services for managing classes, lessons, study results, login histories, etc.
- Integrates with offline services and any API wrappers.
c. Data Layer:
- Represented by the models that encapsulate the data structure.
d. Algorithmic/Utility Layer:
- Contains specialized files (in lib/Algorithm) which use specific algorithms to process and deliver features such as vocabulary matching.
e. Native Platform Integration:
- With separate platform-specific directories (android, ios, web), which handle native configuration, deployment, and platform-related customizations.

##### Relationships & Interactions
- The UI layer (pages and widgets) interacts with the service layer to fetch data, perform actions, and update the view.
- The service layer handles data processing and organizational logic by calling into API modules, offline services, and algorithm components.
- Data models act as a contract between these layers, ensuring that data passed among UI components, services, and algorithms is structured and consistent.
- Native directories (android, ios, web) serve as the runtime containers and provide platform-specific features such as permissions, integrations, and native theming.

##### Architectural Patterns & Design Principles
- Although not explicitly labeled, the separation between UI, business logic (services), and data models shows a layered architectural approach, which is common in Flutter projects.
- The use of modular directories (e.g., pages, components, models, services) suggests an emphasis on separation of concerns and code reusability.
- There might be hints of MVVM or Clean Architecture patterns given the separation between view components and service logic, making it easier for testing and maintenance.

## Diagram (Mermaid)

```mermaid
graph TD
    User["User"]:::external

    subgraph "UI Layer"
        U1["Screens/Pages"]:::ui
        U2["Components"]:::ui
        U3["Widgets"]:::ui
    end

    subgraph "Business Logic Layer"
        S1["Online Services"]:::services
        S2["Offline Services"]:::services
    end

    subgraph "Data & API Layer"
        D1["Data Models"]:::data
        A1["API Integrations"]:::api
    end

    subgraph "Algorithmic Layer"
        AL["Algorithm Utilities"]:::algorithm
    end

    subgraph "Native/Platform Integration"
        N1["Android"]:::native
        N2["iOS"]:::native
        N3["Web"]:::native
    end

    %% User initiates actions on UI
    User -->|"initiates"| U1
    User -->|"initiates"| U2
    User -->|"initiates"| U3

    %% UI Layer triggers service layer
    U1 -->|"triggers"| S1
    U1 -->|"triggers"| S2
    U2 -->|"invokes"| S1
    U3 -->|"invokes"| S1

    %% Service Layer interactions with data and algorithm layers
    S1 -->|"fetches/updats"| D1
    S1 -->|"calls"| A1
    S1 -->|"uses"| AL
    S2 -->|"fetchesOfflineData"| D1
    S2 -->|"uses"| AL

    %% API returns data to Data Models (bidirectional relation)
    A1 -->|"returnsData"| D1

    %% UI Layer deployed on native platforms
    U1 -->|"deployedOn"| N1
    U1 -->|"deployedOn"| N2
    U1 -->|"deployedOn"| N3
    U2 -->|"deployedOn"| N1
    U2 -->|"deployedOn"| N2
    U2 -->|"deployedOn"| N3
    U3 -->|"deployedOn"| N1
    U3 -->|"deployedOn"| N2
    U3 -->|"deployedOn"| N3

    %% Click Events
    click U1 "https://github.com/quangthangit/vocab-korea/tree/main/lib/pages"
    click U2 "https://github.com/quangthangit/vocab-korea/tree/main/lib/components"
    click U3 "https://github.com/quangthangit/vocab-korea/tree/main/lib/widget"
    click S1 "https://github.com/quangthangit/vocab-korea/tree/main/lib/services"
    click S2 "https://github.com/quangthangit/vocab-korea/tree/main/lib/serviceoffline"
    click D1 "https://github.com/quangthangit/vocab-korea/tree/main/lib/models"
    click A1 "https://github.com/quangthangit/vocab-korea/tree/main/lib/api"
    click AL "https://github.com/quangthangit/vocab-korea/tree/main/lib/Algorithm"
    click N1 "https://github.com/quangthangit/vocab-korea/tree/main/android"
    click N2 "https://github.com/quangthangit/vocab-korea/tree/main/ios"
    click N3 "https://github.com/quangthangit/vocab-korea/tree/main/web"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#2874A6,color:#0B3D91,stroke-width:2px;
    classDef services fill:#F9E79F,stroke:#B7950B,color:#7D6608,stroke-width:2px;
    classDef data fill:#D5F5E3,stroke:#239B56,color:#145A32,stroke-width:2px;
    classDef api fill:#FADBD8,stroke:#E74C3C,color:#B03A2E,stroke-width:2px;
    classDef algorithm fill:#E8DAEF,stroke:#8E44AD,color:#5B2C6F,stroke-width:2px;
    classDef native fill:#D6EAF8,stroke:#3498DB,color:#1F618D,stroke-width:2px;
    classDef external fill:#FEF9E7,stroke:#F1C40F,color:#B7950B,stroke-width:2px;
```
