# mohammedsaidi/s_almoulk architecture

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

- Interactive diagram: https://gitdiagram.com/mohammedsaidi/s_almoulk
- Repository: https://github.com/mohammedsaidi/s_almoulk

## Overview

##### Project type and purpose
- This is a cross‐platform Qur’an study application:
- Uses Python/Flet (with Flutter under the hood) to run as desktop, web (Flask + PWA), and mobile (APK)
- Serves a PWA with offline support (service worker + manifest.json)
- Bundles into an Android APK via provided scripts and Android manifest template

##### File structure
- Top‐level Python entrypoints:
- run.py → starts the Flet app
- main.py → Flask app serving web UI + API endpoints
- surah_mulk_app.py → core Application class (business logic, UI definitions in Flet)
- surah_mulk_app_bundle.py → script to generate Android APK
- Static/web assets:
- static/ → CSS, JS (player, PWA init, service‐worker), SVG, manifest.json
- templates/ → HTML templates (index, upload, manage_audio, export_apk)
- Audio & asset storage:
- audio_files/ → persisted user‐uploaded or default audio per verse
- assets/, attached_assets/ → placeholder or pasted resources
- Android packaging:
- android/manifest.template.xml → manifest for APK
- docs in Markdown for APK conversion and Android usage

##### README insights
- Core tech: Python 3.11+, Flet, flet-audio, Flask
- Features: verse display, per‐verse audio, repeat/range controls, offline caching, APK conversion

1. Clients
- Web Browser (PWA)
- Desktop (Flet desktop app)
- Android device (APK)
2. Frontend
- PWA layer: static/js, CSS, templates served by Flask
- Service Worker (cache/offline)
3. Server/API
- Flask App (main.py)
- Endpoints:
- GET templates & static assets
- POST/GET audio uploads (manage_audio.html, upload.html)
4. Core Application
- Flet Application class (surah_mulk_app.py)
- UI definitions + business logic (verse navigation, audio control)
5. Storage
- File System: audio_files/ (verse audio files)
- assets/ & attached_assets/
6. Build/Packaging
- APK packaging script (surah_mulk_app_bundle.py)
- Android manifest template
- CI workflow (only-zip.yml)

- Browser ↔ Flask (HTTP)
- Flask ↔ File System (read/write audio_files/)
- Browser ↔ Service Worker (intercepts, caches assets + audio)
- run.py → loads surah_mulk_app.py (in‐process Flet host)
- Flet UI → audio_files (local file I/O)
- APK Script → invokes Flet build → Android manifest
- CI Workflow → triggers packaging, zipping resources

c. Architectural patterns / design principles:
- MVC‐like for web:
- Model = audio_files + business state in surah_mulk_app.py
- View = templates + static assets + Flet UI widgets
- Controller = Flask routes + Flet event handlers
- PWA caching strategy (service‐worker) for offline mode
- Single‐codebase multi-target via Flet (reuse Python UI logic)
- File‐based storage (no external DB)

d. Key technologies/frameworks:
- Python 3.11, Flask, Flet, flet-audio
- HTML/CSS/JS (vanilla + service-worker)
- Android build via Flet’s APK bundler

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        Browser["Web Browser"]:::client
        Desktop["Desktop App"]:::client
        AndroidClient["Android Device"]:::client
    end

    %% Web Layer
    subgraph "Web Frontend (PWA layer)"
        CSS["CSS"]:::frontend
        JS["JS"]:::frontend
        Icons["Icons"]:::frontend
        Manifest["manifest.json"]:::frontend
    end

    subgraph "HTML Templates"
        Index["index.html"]:::frontend
        Upload["upload.html"]:::frontend
        Manage["manage_audio.html"]:::frontend
        Export["export_apk.html"]:::frontend
    end

    ServiceWorker["Service Worker"]:::frontend
    PWAInit["PWA Init Script"]:::frontend
    Player["Audio Player Script"]:::frontend

    %% Server/API
    subgraph "Server/API"
        Flask["Flask Server"]:::server
    end

    %% Core App
    subgraph "Core Application"
        Run["run.py"]:::core
        CoreApp["surah_mulk_app.py"]:::core
    end

    %% Storage
    subgraph "Storage"
        AudioStorage["Audio Files"]:::storage
        Assets["Assets"]:::storage
        AttachedAssets["Attached Assets"]:::storage
    end

    %% Build/CI
    subgraph "Build & CI"
        APKScript["APK Packaging Script"]:::build
        ManifestTemplate["Android Manifest Template"]:::build
        AndroidRes["Android Resources"]:::build
        CI["CI Workflow"]:::build
    end

    %% Connections
    Browser -->|HTTP| Flask
    Browser -->|registers| ServiceWorker
    ServiceWorker -->|caches| CSS
    ServiceWorker -->|caches| JS
    ServiceWorker -->|caches| Icons
    ServiceWorker -->|caches| Manifest
    ServiceWorker -->|caches| AudioStorage
    Flask -->|serves static| CSS
    Flask -->|serves static| JS
    Flask -->|serves templates| Index
    Flask -->|serves templates| Upload
    Flask -->|serves templates| Manage
    Flask -->|serves templates| Export
    Flask -->|read/write| AudioStorage
    Desktop -->|launches| Run
    Run -->|loads| CoreApp
    CoreApp -->|UI widgets| Desktop
    CoreApp -->|file I/O| AudioStorage
    CoreApp -->|access| Assets
    CoreApp -->|access| AttachedAssets
    APKScript -->|invokes| CoreApp
    APKScript -->|uses| ManifestTemplate
    APKScript -->|includes| AndroidRes
    CI -->|triggers| APKScript
    AndroidClient -->|installs APK| APKScript

    %% Click Events
    click CSS "https://github.com/mohammedsaidi/s_almoulk/tree/main/static/css/"
    click JS "https://github.com/mohammedsaidi/s_almoulk/tree/main/static/js/"
    click Icons "https://github.com/mohammedsaidi/s_almoulk/tree/main/static/icons/"
    click Manifest "https://github.com/mohammedsaidi/s_almoulk/blob/main/static/manifest.json"
    click Index "https://github.com/mohammedsaidi/s_almoulk/blob/main/templates/index.html"
    click Upload "https://github.com/mohammedsaidi/s_almoulk/blob/main/templates/upload.html"
    click Manage "https://github.com/mohammedsaidi/s_almoulk/blob/main/templates/manage_audio.html"
    click Export "https://github.com/mohammedsaidi/s_almoulk/blob/main/templates/export_apk.html"
    click ServiceWorker "https://github.com/mohammedsaidi/s_almoulk/blob/main/static/js/service-worker.js"
    click PWAInit "https://github.com/mohammedsaidi/s_almoulk/blob/main/static/js/pwa-init.js"
    click Player "https://github.com/mohammedsaidi/s_almoulk/blob/main/static/js/player.js"
    click Flask "https://github.com/mohammedsaidi/s_almoulk/blob/main/main.py"
    click Run "https://github.com/mohammedsaidi/s_almoulk/blob/main/run.py"
    click CoreApp "https://github.com/mohammedsaidi/s_almoulk/blob/main/surah_mulk_app.py"
    click APKScript "https://github.com/mohammedsaidi/s_almoulk/blob/main/surah_mulk_app_bundle.py"
    click ManifestTemplate "https://github.com/mohammedsaidi/s_almoulk/blob/main/android/manifest.template.xml"
    click AndroidRes "https://github.com/mohammedsaidi/s_almoulk/tree/main/android/res/"
    click AudioStorage "https://github.com/mohammedsaidi/s_almoulk/tree/main/audio_files/"
    click Assets "https://github.com/mohammedsaidi/s_almoulk/tree/main/assets/"
    click AttachedAssets "https://github.com/mohammedsaidi/s_almoulk/tree/main/attached_assets/"
    click CI "https://github.com/mohammedsaidi/s_almoulk/blob/main/.github/workflows/only-zip.yml"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000
    classDef frontend fill:#ADD8E6,stroke:#000
    classDef server fill:#90EE90,stroke:#000
    classDef core fill:#FFFFE0,stroke:#000
    classDef storage fill:#FFA500,stroke:#000
    classDef build fill:#D3D3D3,stroke:#000
```
