# ducngg/v7 architecture

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

- Interactive diagram: https://gitdiagram.com/ducngg/v7
- Repository: https://github.com/ducngg/v7

## Overview

##### Project type and purpose
- This is a desktop-style Vietnamese input method application (“v7”) written in Python 3.12.
- It combines a rule-based input-method engine with an optional AI-powered predictor (a nanoGPT-derived model) to turn partial keystrokes into full Vietnamese text.

##### File structure
- Top-level:
- main.py / main_app.py – entry points
- requirements.txt / requirements_ai.txt – deps for core vs AI modes
- checkpoints/ – persisted JSON dictionaries & model checkpoints
- assets/ – static files (demo GIF, images)
- ai/ – code for model config, tokenizer, model definition, inference utilities
- imethod/ – core input-method logic (v7 rules + AI hook)
- app/ – application orchestration & UI:
- app.py – glues listener, processor, UI
- listener.py – captures keystrokes
- gui.py – renders suggestions, popup window
- args.py, properties.py, combinations.py, utils.py – CLI flags, settings, helper routines
- models/ – domain models (dictionary structures, app config, imethod abstractions)
- utils/ – shared helpers (preprocessing, logging, unicode/dictionary utilities)
- sandbox/ – experimental scripts

##### README for additional insights
- Two modes:
- Classical (“VNI‐compatible” 8-tone mapping) via imethod/v7.py
- AI Mode via imethod/v7ai.py + ai/model.py + tokenizer, using a pretrained GPT checkpoint
- Data flow: keystroke → rule-based lookup or AI model → ranked suggestions → user picks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        User[/"User"/]:::io
        GUI["GUI\n(app/gui.py)"]:::ui
        Listener["Keyboard Listener\n(app/listener.py)"]:::ui
    end

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        EntryMain["main.py\n(Entry Point)"]:::controller
        EntryMainApp["main_app.py\n(Entry Point)"]:::controller
        Orchestrator["Orchestrator\n(app/app.py)"]:::controller
        Settings["CLI Flags & Settings\n(app/args.py, app/properties.py)"]:::settings
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        Preprocessor["Input Preprocessor\n(utils/preprocess.py)"]:::process
    end

    %% Prediction Engines
    subgraph "Prediction Engines"
        direction TB
        subgraph "Classical Mode"
            direction TB
            RuleEngine["Rule-Based Engine\n(imethod/v7.py)"]:::engine
            RuleData["Dictionary Model\n(models/dictionary.py)"]:::engine
        end
        subgraph "AI Mode"
            direction TB
            AIConfig["AI Config\n(ai/configs.py)"]:::engine
            AITokenizer["AI Tokenizer\n(ai/tokenizer.py)"]:::engine
            AIModel["AI Engine\n(ai/model.py)"]:::engine
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SharedUtils["Shared Utilities\n(utils/logging.py, utils/dictionary.py, utils/vietnamese.py)"]:::util
        DataStore["Data Store\n(checkpoints/*.json, .txt)"]:::data
        CheckpointFile["Model Checkpoint\n(checkpoints/v7gpt-*.pth)"]:::ext
    end

    %% Flows
    User -->|"interacts"| GUI
    GUI -->|"captures keystrokes"| Listener
    Listener -->|"raw input"| Preprocessor
    Preprocessor -->|"processed input"| Orchestrator
    Settings -->|"configures"| Orchestrator
    EntryMain --> Orchestrator
    EntryMainApp --> Orchestrator

    Orchestrator -->|"if Classical Mode"| RuleEngine
    RuleEngine --> RuleData
    RuleData --> DataStore

    Orchestrator -->|"if AI Mode"| AIConfig
    AIConfig --> AITokenizer
    AITokenizer --> AIModel
    AIModel --> CheckpointFile
    AIModel --> DataStore

    RuleEngine -->|"suggestions"| Orchestrator
    AIModel -->|"suggestions"| Orchestrator

    Orchestrator -->|"deliver suggestions"| GUI
    GUI -->|"displays suggestions"| User

    Orchestrator --> SharedUtils
    RuleEngine --> SharedUtils
    AIModel --> SharedUtils
    Preprocessor --> SharedUtils

    %% Click Events
    click EntryMain "https://github.com/ducngg/v7/blob/main/main.py"
    click EntryMainApp "https://github.com/ducngg/v7/blob/main/main_app.py"
    click Orchestrator "https://github.com/ducngg/v7/blob/main/app/app.py"
    click Listener "https://github.com/ducngg/v7/blob/main/app/listener.py"
    click GUI "https://github.com/ducngg/v7/blob/main/app/gui.py"
    click Settings "https://github.com/ducngg/v7/blob/main/app/args.py"
    click Settings "https://github.com/ducngg/v7/blob/main/app/properties.py"
    click Preprocessor "https://github.com/ducngg/v7/blob/main/utils/preprocess.py"
    click RuleEngine "https://github.com/ducngg/v7/blob/main/imethod/v7.py"
    click RuleData "https://github.com/ducngg/v7/blob/main/models/dictionary.py"
    click AIModel "https://github.com/ducngg/v7/blob/main/ai/model.py"
    click AITokenizer "https://github.com/ducngg/v7/blob/main/ai/tokenizer.py"
    click AIConfig "https://github.com/ducngg/v7/blob/main/ai/configs.py"
    click SharedUtils "https://github.com/ducngg/v7/blob/main/utils/logging.py"
    click SharedUtils "https://github.com/ducngg/v7/blob/main/utils/dictionary.py"
    click SharedUtils "https://github.com/ducngg/v7/blob/main/utils/vietnamese.py"
    click DataStore "https://github.com/ducngg/v7/blob/main/checkpoints/db.json"
    click DataStore "https://github.com/ducngg/v7/blob/main/checkpoints/dict.json"
    click DataStore "https://github.com/ducngg/v7/blob/main/checkpoints/enum.json"
    click DataStore "https://github.com/ducngg/v7/blob/main/checkpoints/renum.json"
    click DataStore "https://github.com/ducngg/v7/blob/main/checkpoints/renum_crt.json"
    click DataStore "https://github.com/ducngg/v7/blob/main/checkpoints/db_update_log.txt"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef io fill:#B0E0E6,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
    classDef controller fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef process fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef engine fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef ext fill:#FF7F7F,stroke:#000,stroke-width:1px;
    classDef settings fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
