""" Generate an executive, publication-grade Architecture & Workflow Specification PDF for Sahih Islam. Uses WeasyPrint to render clean HTML5/CSS3 into a high-resolution PDF. """ import os import sys sys.stdout.reconfigure(encoding='utf-8') from pathlib import Path import weasyprint OUTPUT_PDF = Path("D:/Project-x/SahihIslam_Architecture_Workflow.pdf") HTML_CONTENT = """ Sahih Islam — System Architecture & Workflow Specification

Sahih Islam Enterprise Architecture

Comprehensive System Workflow, Component Functionality & Data Flow Blueprint

Sahih Islam is engineered as a high-precision, low-latency, distributed Islamic intelligence ecosystem. It integrates an offline-capable cross-platform mobile client with an asynchronous backend, distributed object storage, in-memory caching, double-entry financial ledger accounting, and a pure cloud high-performance semantic search and RAG engine.

1. Executive Component Matrix: What Everything Actually Does

Every tier in the stack serves a strictly defined, non-overlapping architectural purpose:

Technology	Role in Stack	Actual Real-World Function & Responsibilities
FastAPI Backend Gateway	Asynchronous Python REST & SSE Server	• Routes all client requests (auth, hadith, quran, payments, ads, masjids). • Serves non-blocking Server-Sent Events (SSE) and NDJSON for real-time AI token streaming. • Orchestrates cloud neural inference bridges (BGE-M3 bi-encoder + cross-encoder reranker). • Validates JWTs, processes Razorpay/Google Play webhooks, orchestrates background jobs.
MongoDB Atlas Primary Database	Multi-Collection Document & Vector Store	• Stores structured relational-like data: 24,356 Hadiths, 114 Surahs, 6,236 Ayahs, Users. • Runs Atlas Vector Search (`$vectorSearch`) using 1024-dim HNSW cosine index. • Stores double-entry financial ledgers (Wallets, Transactions, Invoices). • Geospatial queries for Masjids (2dsphere index for nearby prayer facilities).
Cloudflare R2 Object Storage	S3-Compatible Zero-Egress Storage & Edge CDN	• Stores large binary assets outside MongoDB to prevent database bloat. • Houses complete 114 Surah recitations (Mishary Alafasy high-quality audio files). • Hosts Urdu & English Tafseer audio libraries (Dr. Israr Ahmed, Maududi). • Distributes 8 multi-language Quran translation bundles (EN, UR, HI, FR, ES, ID, TR, BN). • Caches and streams 16-line Mushaf Hafizi PDFs and advertiser media creatives globally with zero egress bandwidth fees.
Redis / Upstash In-Memory Cache	Sub-millisecond State & Distributed Cache	• Caches repetitive, read-heavy data (Prayer calculation parameters, daily Hadith pool). • Rate limiting & IP throttling to safeguard expensive AI vector inference endpoints. • Distributed locks for atomic wallet debit operations (prevents race-condition double spends). • Caches active user tokens and real-time ad impression frequency counters.
Flutter Client Frontend Application	Multi-Platform UI (Android, iOS, Web)	• Renders responsive interfaces for Quran, Hadith, Tasbeeh, Ads Marketplace, and Masjid Finder. • Offline-first capabilities: Local SQLite/Hive caches recent Quran, Tasbeeh counts, and settings. • Executes high-precision astronomical prayer calculation algorithms locally on device. • Native audio player engine with background playback, seek bars, and auto-scrolling Ayah markers.
SuperAdmin Control Plane	Enterprise Operations & Moderation Portal	• Real-time financial telemetry (Wallet flows, platform earnings, payment gateway health). • Ad review pipeline (Approve, reject, or pause advertisers' commercial campaigns). • Mufti verification, Masjid claim dispute resolution, and audit log inspection.

2. Deep-Dive Component Architecture

A. FastAPI — The High-Throughput Orchestrator

Unlike traditional synchronous frameworks (e.g. Django, Flask), FastAPI runs on top of Starlette and Uvicorn utilizing Python's asynchronous event loop (asyncio). In Sahih Islam, every database call uses Motor (non-blocking async MongoDB driver) so a single server process can sustain thousands of concurrent connections without thread exhaustion.

Key Internal Engines inside FastAPI:

High-Speed Cloud Neural Engine: Highly scalable 1024-dim BGE-M3 bi-encoder embeddings and cross-encoder neural reranking routed via dedicated cloud API providers (OpenRouter, Jina, Cohere) with zero container RAM/CPU overhead.
NDJSON / SSE Streaming Pipeline: For the search/ask endpoint (/api/hadith/ask), FastAPI streams AI responses word-by-word as NDJSON chunks. This eliminates user perceived latency.
Background Task Dispatcher: Post-query operations (such as saving conversation history, recording ad impressions, and vectorizing memory) are dispatched to BackgroundTasks so the HTTP response returns immediately.

B. MongoDB Atlas — The Ground Truth & Vector Knowledge Base

MongoDB acts as the permanent system of record. It is structured into high-performance collections with targeted indexes:

hadiths (24,356 items): Contains the Arabic Matn, English translation, Urdu translation, Sanad (narrator chain), grade, and pre-computed 1024-dimensional embedding_1024 vectors.
quran & quran_verses (114 Surahs / 6,236 Ayahs): Verse-level records indexed by Surah number and Ayah number with linguistic tafseer references.
wallets & transactions: Implements transactional double-entry accounting. Wallets store available balance, locked balance, and currency. Every credit or debit logs an immutable transaction record.
ads & ad_analytics: Stores advertiser campaigns, targeting parameters, daily budget, remaining wallet balance, and real-time impression counts.
vector_memory: Stores past user conversations embedded into vector space so the AI can recall previous discussions in follow-up queries.

C. Cloudflare R2 — Heavy Object & Audio CDN

Storing gigabytes of audio and PDF files inside MongoDB would degrade database performance, bloat backups, and skyrocket RAM costs. Sahih Islam solves this by offloading all static media to Cloudflare R2:

Zero Egress Bandwidth Pricing: Traditional clouds (AWS S3, GCP) charge \$0.08–\$0.12 per GB downloaded. Streaming gigabytes of high-quality Quran recitation audio daily would cost hundreds of dollars. Cloudflare R2 charges \$0.00 for egress bandwidth.
Global Edge Caching: R2 connects directly to Cloudflare’s CDN across 300+ global cities. When a user in the UK, USA, or South Asia plays an audio file, it is delivered from the nearest local edge server with instant time-to-first-byte (TTFB).
Storage Breakdown:
• /surah_audio/: 114 recitations in 128kbps/64kbps MP3.
• /tafseer_audio/: Thousands of detailed Tafseer lectures.
• /quran_translations/: Clean JSON translation files across 8 major world languages.
• /mushaf_pdfs/: 16-line and 15-line high-resolution Mushaf pages.

D. Redis / Upstash — Sub-Millisecond Speed Layer

Redis operates entirely in RAM. It handles functions where a disk-based database would be too slow:

Rate Limiting: Enforces user quotas (e.g., max 20 AI searches per minute for free users, 100 for Pro users) using Redis token buckets.
Hot Query Caching: Common queries (e.g. "Surah Al-Mulk translation", "Ayah of the day", "Fajr prayer calculation constants") are cached in Redis with a TTL. Requests return in < 2 milliseconds without hitting MongoDB.
Atomic Locks for Payments: When an ad is displayed and money is deducted from an advertiser's wallet, Redis handles atomic counter decrements (DECRBY) to prevent balance underflow or race conditions.

3. Complete End-to-End Workflows & Data Flows

Workflow 1: The AI RAG Search Engine (User Ask Page)

How the system processes an Islamic question through neural retrieval, verification, and streaming:

User Prompt Input & Intent Routing (Flutter → FastAPI)

The user types a query (e.g. "What does Quran say about patience in hardship?") or selects books (Quran, Sahih al-Bukhari, Muslim). Flutter sends an HTTP POST request to /api/hadith/ask. FastAPI analyzes the intent using a local Intent Classifier.

Bi-Encoder Query Vectorization (Cloud Neural BGE-M3)

FastAPI passes the query to the high-performance BGE-M3 bi-encoder. It transforms the query text into a normalized 1,024-dimensional dense vector.

Parallel MongoDB Atlas Vector Search ($vectorSearch)

FastAPI dispatches parallel queries into MongoDB Atlas:

{"$vectorSearch": {"index": "vector_index", "path": "embedding_1024", "queryVector": [...], "numCandidates": 100, "limit": 20}}

Atlas retrieves the top 20 mathematically closest candidate Hadiths and Quran verses using HNSW Cosine Similarity.

Cross-Encoder Neural Reranking (Precision Gate)

Bi-encoder recall brings potential candidates, but some might be superficially related. FastAPI pairs the query with each candidate text and runs them through the Cloud Cross-Encoder Reranker. Pairs with low relevance logits (< 0.0) are discarded. Candidates are sorted in order of absolute factual relevance.

Dynamic Semantic Boundary Expansion (Cloudflare R2 Context Injection)

For Quranic verses, an Ayah often belongs to a passage. FastAPI fetches the full Surah JSON from Cloudflare R2 / MongoDB cache, detects the surrounding Ayahs with high semantic continuation, attaches Arabic text with verse badges (e.g. ﴿153﴾), and appends audio recitation links.

Zero-Hallucination Strict LLM Generation & NDJSON Streaming

The verified religious texts are injected into the LLM system prompt under strict zero-extrapolation guardrails. Tokens are streamed live back to Flutter via StreamingResponse(media_type="application/x-ndjson"). The Flutter UI paints the words in real time with clickable source badges, audio player controls, and transliterations.

Workflow 2: The AADS Marketplace & Wallet Deduction Lifecycle

How the system serves ads, protects advertiser budgets, and handles usage-based wallet deduction:

Campaign Creation & Wallet Balance Verification

An advertiser creates an ad campaign in Flutter. The Flutter app verifies that the user's wallet balance in wallets covers the campaign total. If balance is insufficient, creation is rejected with an instant top-up modal.

Non-Sequential Weighted Probability Selection (AADS Feed)

When standard users scroll through the feed, Flutter requests an ad. FastAPI fetches all active campaigns with remaining daily budget and balance > 0. Instead of boring sequential loops, it computes a weighted probability distribution (based on bid tier, relevance, and impression targets) to return a randomized, high-yield ad.

Usage-Based Deductions (Post-Impression / Click)

The advertiser's money is not deducted all at once upon posting. Instead, when Flutter reports a verified impression (2+ seconds view) or click, FastAPI executes an atomic debit:

wallets.update_one({"user_id": seller_id, "balance": {"$gte": cost_per_click}}, {"$inc": {"balance": -cost_per_click}})

This guarantees fair, usage-based pay-as-you-go billing.

Workflow 3: Quran Audio & Multi-Language Translation Delivery

1. Translation Delivery Pipeline

Flutter requests translations for a Surah. Instead of burdening MongoDB with repetitive full-text pulls, requests are routed directly to Cloudflare R2 (/quran_translations/{lang}.json). Cloudflare's CDN caches the response at the edge, serving 114 Surahs across 8 languages in < 30ms.

2. Audio Recitation Streaming

When a user taps play on Ayah recitation or Tafseer, Flutter connects to Cloudflare R2's streaming endpoints. The native just_audio plugin handles chunked buffering, background lock-screen notifications, and emits Ayah completion events to automatically highlight the current verse.

4. Architecture Summary & Design Principles

Strict Separation of Concerns: Static heavy assets live in Cloudflare R2. High-speed caching and locks live in Redis. Rich relational and vector data live in MongoDB Atlas. Computational inference and business logic live in FastAPI. Rendering and offline state live in Flutter.
Zero Data Lock-in & Predictable Costs: Using Cloudflare R2 eliminates egress fees. Using managed neural cloud endpoints eliminates server RAM/GPU maintenance costs.
Absolute Factual Rigor: The RAG architecture utilizes a dual-gate (Bi-encoder recall + Cross-encoder precision) combined with dynamic semantic boundary detection, preventing generative hallucinations in Islamic knowledge retrieval.

""" def generate_pdf(): print(f"📄 Compiling HTML and generating PDF via WeasyPrint...") html = weasyprint.HTML(string=HTML_CONTENT) html.write_pdf(str(OUTPUT_PDF)) print(f"✅ PDF successfully generated at: {OUTPUT_PDF}") print(f" File size: {OUTPUT_PDF.stat().st_size / 1024:.1f} KB") if __name__ == "__main__": generate_pdf()