How mohammedsaidi/s_almoulk works
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