# sekodev/openbilgi architecture

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

- Interactive diagram: https://gitdiagram.com/sekodev/openbilgi
- Repository: https://github.com/sekodev/openbilgi

## Overview

##### Project type and purpose
- This is a cross-platform trivia/quiz game (“OpenBilgi”) built on the Solar2D engine (formerly Corona SDK).
- Its purpose is to present question sets (in multiple languages), manage game states (menu, game, success, end, stats, etc.), play music/sound effects, and record preferences/stats.

##### File structure
- Top-level files: build.settings, config.lua, main.lua (entry point), README, license files.
- libs/: reusable Lua modules (composer_alt, preference, rng, commonMethods, utils, translations, etc.).
- screens/: one Lua file per Composer scene (menuScreen.lua, gameScreen.lua, creditScreen.lua, etc.).
- questions/: language-specific questionSetX.lua files.
- storeFiles/: marketing assets for Google Play (screenshots, banners) and legal docs (privacyPolicy, termsUse).
- translations/: top-level language mappings (en.lua, tr.lua).

##### README for additional insights
- Confirms dependency on Solar2D runtime v2024.3710.
- Lists external libraries: Pseudorandom Number Generator, Preference, sozluk (dictionary).
- Details asset licenses (music, SFX, font).

##### Main components
a. Solar2D Engine (runtime)
b. Application Core
- main.lua & config.lua (initialization & config)
- build.settings (platform settings)
c. Scene Manager
- composer_alt (wrapper over Composer API)
- screens/* (menuScreen, gameScreen, etc.)
d. Game Logic & Data
- libs/ (core modules: RNG, preference, commonMethods, utils)
- questions/ (localized question sets)
- translations/ (text localization)
e. Asset Layer
- assets/ (audio, images, particleFX)
f. External Services & Marketing
- storeFiles/ (Google Play images, privacy policy, terms)
- (future extension point for ads or analytics)

##### Relationships & interactions
- The Solar2D Engine loads main.lua → reads config → invokes Scene Manager.
- Scene Manager uses composer_alt to transition between screens.
- Each screen requests data from Game Logic modules (questions, translations, RNG, preference).
- Assets (audio/images/particleFX) are loaded on demand by screens.
- Preference library persists settings & stats.
- On build, build.settings + platform resources configure packaging for iOS/Android.
- storeFiles are only used at release time for marketing.

##### Architectural patterns & design principles
- Layered architecture: Engine → Application Core → Scene Management → Business Logic → Assets/Data.
- Separation of concerns: UI (screens) vs. logic (libs) vs. data (questions/translations) vs. resources.
- Plugin-style extensibility: new libs or question sets can be dropped into directories.
- Localization through file-based translation modules.

- Startup sequence
- Scene transitions
- Data requests (question fetch, translation lookup)
- Asset loads (audio, images, particleFX)
- Persistence actions (preference writes/reads)
- Modules with their file paths (e.g., libs/preference.lua).
- Every file group (screens, libs, questions, assets) is represented as a logical component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Engine Layer
    subgraph "Engine"
        Engine["Solar2D Engine (Runtime)"]:::engine
    end

    %% Application Core Layer
    subgraph "Application Core"
        Main["main.lua"]:::core
        Config["config.lua"]:::core
        BuildSettings["build.settings"]:::core
    end

    %% Scene Management Layer
    subgraph "Scene Manager & Screens"
        Composer["composer_alt (Scene Manager)"]:::scene
        subgraph "Screens"
            MenuScreen["menuScreen.lua"]:::scene
            GameScreen["gameScreen.lua"]:::scene
            LogoScreen["logoScreen.lua"]:::scene
            SuccessScreen["successScreen.lua"]:::scene
            EndScreen["endScreen.lua"]:::scene
            StatsScreen["statsScreen.lua"]:::scene
            SettingScreen["settingScreen.lua"]:::scene
            CreditScreen["creditScreen.lua"]:::scene
        end
    end

    %% Game Logic & Data Layer
    subgraph "Game Logic & Data"
        subgraph "Core Libraries"
            RNG["rng.lua"]:::data
            Preference["preference.lua"]:::data
            CommonMethods["commonMethods.lua"]:::data
            Utils["utils.lua"]:::data
            TransHelper["translations.lua"]:::data
            Sozluk["sozluk.lua"]:::data
            ThemeSettings["themeSettings.lua"]:::data
            ParticleDesigner["particleDesigner.lua"]:::data
            InfoCredits["infoCredits.lua"]:::data
        end
        subgraph "Question Sets"
            QuestionsDir["/questions/"]:::data
        end
        subgraph "Translation Mappings"
            TransEn["en.lua"]:::data
            TransTr["tr.lua"]:::data
        end
    end

    %% Assets Layer
    subgraph "Asset Layer"
        subgraph "Audio"
            Music["/assets/music/"]:::assets
            SoundFX["/assets/soundFX/"]:::assets
        end
        subgraph "Images & UI"
            MenuIcons["/assets/menu/"]:::assets
            OtherImages["/assets/other/"]:::assets
        end
        ParticleFX["/assets/particleFX/"]:::assets
        RawFiles["/assets/rawFiles/"]:::assets
        subgraph "Platform Icons"
            AndroidIcons["AndroidResources/"]:::assets
            iOSIcons["Images.xcassets/"]:::assets
        end
    end

    %% External & Marketing Layer
    subgraph "External Services & Marketing"
        GooglePlay["/storeFiles/googlePlay/"]:::external
        subgraph "Legal Docs"
            Privacy["/storeFiles/privacyPolicy/"]:::external
            Terms["/storeFiles/termsUse/"]:::external
        end
    end

    %% Connections
    Engine -->|loads| Main
    Main -->|reads config| Config
    Config -->|initializes build| BuildSettings
    Config -->|starts| Composer

    Composer -->|manages scenes| MenuScreen
    Composer --> GameScreen
    Composer --> LogoScreen
    Composer --> SuccessScreen
    Composer --> EndScreen
    Composer --> StatsScreen
    Composer --> SettingScreen
    Composer --> CreditScreen

    MenuScreen -->|requests data| RNG
    MenuScreen --> Preference
    MenuScreen --> CommonMethods
    MenuScreen --> Utils
    MenuScreen --> TransHelper
    MenuScreen --> Sozluk
    MenuScreen --> QuestionsDir
    MenuScreen --> TransEn
    MenuScreen --> TransTr
    MenuScreen --> Music
    MenuScreen --> SoundFX
    MenuScreen --> MenuIcons
    MenuScreen --> ParticleFX

    GameScreen -->|similar load| Music
    GameScreen --> SoundFX
    GameScreen --> ParticleFX
    GameScreen --> QuestionsDir
    GameScreen --> TransHelper
    GameScreen --> Preference

    SuccessScreen -->|uses assets| OtherImages
    EndScreen -->|uses assets| OtherImages
    StatsScreen --> Preference

    Preference -->|persists| BuildSettings

    %% Click Events
    click Main "https://github.com/sekodev/openbilgi/blob/main//main.lua"
    click Config "https://github.com/sekodev/openbilgi/blob/main//config.lua"
    click BuildSettings "https://github.com/sekodev/openbilgi/blob/main//build.settings"
    click Composer "https://github.com/sekodev/openbilgi/blob/main//libs/composer_alt.lua"
    click MenuScreen "https://github.com/sekodev/openbilgi/blob/main//screens/menuScreen.lua"
    click GameScreen "https://github.com/sekodev/openbilgi/blob/main//screens/gameScreen.lua"
    click LogoScreen "https://github.com/sekodev/openbilgi/blob/main//screens/logoScreen.lua"
    click SuccessScreen "https://github.com/sekodev/openbilgi/blob/main//screens/successScreen.lua"
    click EndScreen "https://github.com/sekodev/openbilgi/blob/main//screens/endScreen.lua"
    click StatsScreen "https://github.com/sekodev/openbilgi/blob/main//screens/statsScreen.lua"
    click SettingScreen "https://github.com/sekodev/openbilgi/blob/main//screens/settingScreen.lua"
    click CreditScreen "https://github.com/sekodev/openbilgi/blob/main//screens/creditScreen.lua"
    click RNG "https://github.com/sekodev/openbilgi/blob/main//libs/rng.lua"
    click Preference "https://github.com/sekodev/openbilgi/blob/main//libs/preference.lua"
    click CommonMethods "https://github.com/sekodev/openbilgi/blob/main//libs/commonMethods.lua"
    click Utils "https://github.com/sekodev/openbilgi/blob/main//libs/utils.lua"
    click TransHelper "https://github.com/sekodev/openbilgi/blob/main//libs/translations.lua"
    click Sozluk "https://github.com/sekodev/openbilgi/blob/main//libs/sozluk.lua"
    click ThemeSettings "https://github.com/sekodev/openbilgi/blob/main//libs/themeSettings.lua"
    click ParticleDesigner "https://github.com/sekodev/openbilgi/blob/main//libs/particleDesigner.lua"
    click InfoCredits "https://github.com/sekodev/openbilgi/blob/main//libs/infoCredits.lua"
    click QuestionsDir "https://github.com/sekodev/openbilgi/tree/main//questions/"
    click TransEn "https://github.com/sekodev/openbilgi/blob/main//translations/en.lua"
    click TransTr "https://github.com/sekodev/openbilgi/blob/main//translations/tr.lua"
    click Music "https://github.com/sekodev/openbilgi/tree/main//assets/music/"
    click SoundFX "https://github.com/sekodev/openbilgi/tree/main//assets/soundFX/"
    click MenuIcons "https://github.com/sekodev/openbilgi/tree/main//assets/menu/"
    click OtherImages "https://github.com/sekodev/openbilgi/tree/main//assets/other/"
    click ParticleFX "https://github.com/sekodev/openbilgi/tree/main//assets/particleFX/"
    click RawFiles "https://github.com/sekodev/openbilgi/tree/main//assets/rawFiles/"
    click AndroidIcons "https://github.com/sekodev/openbilgi/tree/main//AndroidResources/res/"
    click iOSIcons "https://github.com/sekodev/openbilgi/tree/main//Images.xcassets/"
    click GooglePlay "https://github.com/sekodev/openbilgi/tree/main//storeFiles/googlePlay/"
    click Privacy "https://github.com/sekodev/openbilgi/tree/main//storeFiles/privacyPolicy/"
    click Terms "https://github.com/sekodev/openbilgi/tree/main//storeFiles/termsUse/"

    %% Styles
    classDef engine fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#BEE3F8,stroke:#3182CE,color:#3182CE
    classDef scene fill:#C6F6D5,stroke:#38A169,color:#2F855A
    classDef data fill:#FED7AA,stroke:#DD6B20,color:#C05621
    classDef assets fill:#FEFCBF,stroke:#D69E2E,color:#B7791F
    classDef external fill:#E9D8FD,stroke:#9F7AEA,color:#6B46C1
```
