Commit ·
2e0a4d0
1
Parent(s): b2519df
docs: add complete product and ecosystem audit
Browse files- BAYAN_COMPLETE_AUDIT.md +115 -0
BAYAN_COMPLETE_AUDIT.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# BAYAN — Complete Product, Codebase & Extension Deep Audit
|
| 2 |
+
|
| 3 |
+
## 1. Current System Overview
|
| 4 |
+
|
| 5 |
+
Bayan is a full-featured Arabic AI writing assistant deployed across two primary surfaces: a web application and a Chrome extension.
|
| 6 |
+
The core architecture is built around a centralized Flask API hosted on Hugging Face Spaces (`bayan10-bayan-api.hf.space`), which serves NLP models for spelling, grammar, punctuation, summarization, dialect conversion, and Quranic validation.
|
| 7 |
+
|
| 8 |
+
**Website Architecture:**
|
| 9 |
+
- **Frontend:** Vanilla JS, HTML, CSS (Tailwind via CDN). Uses a custom `contenteditable` editor engine.
|
| 10 |
+
- **Backend:** Flask API handling model inference.
|
| 11 |
+
- **Database/Auth:** Supabase for cloud persistence, document sync, and authentication (Guest & Google).
|
| 12 |
+
|
| 13 |
+
**Extension Architecture:**
|
| 14 |
+
- **Framework:** Manifest V3.
|
| 15 |
+
- **Components:** Background Service Worker (`background.js`), Content Scripts (`content-inline.js`), Sidepanel, and Popup.
|
| 16 |
+
- **Communication:** Background worker acts as the single network boundary to the HF API.
|
| 17 |
+
|
| 18 |
+
---
|
| 19 |
+
|
| 20 |
+
## 2. Feature Inventory
|
| 21 |
+
|
| 22 |
+
| Feature | Website | Extension | Status | Required Action |
|
| 23 |
+
|---------|---------|-----------|--------|-----------------|
|
| 24 |
+
| **Spelling/Grammar/Punctuation** | ✅ Exists | ✅ Exists | Parity | None |
|
| 25 |
+
| **Summarization** | ✅ Exists | ✅ Exists | Parity | None |
|
| 26 |
+
| **AutoComplete** | ✅ Exists | ❌ Missing | Gap | Implement inline text prediction in `content-inline.js` |
|
| 27 |
+
| **Dialect Conversion** | ✅ Exists | ❌ Missing | Gap | Add to Extension Sidepanel |
|
| 28 |
+
| **Quran Validation** | ✅ Exists | ❌ Missing | Gap | Add to Extension Sidepanel |
|
| 29 |
+
| **Document Cloud Save** | ✅ Exists | ❌ Missing | Gap | Integrate Supabase into Extension |
|
| 30 |
+
| **Authentication** | ✅ Exists | ❌ Missing | Gap | Implement shared auth state via cookies/Supabase |
|
| 31 |
+
| **Settings Sync** | ✅ Exists | ❌ Missing | Gap | Share user preferences via Supabase |
|
| 32 |
+
|
| 33 |
+
---
|
| 34 |
+
|
| 35 |
+
## 3. Website vs Extension Comparison
|
| 36 |
+
|
| 37 |
+
### Authentication
|
| 38 |
+
- **Website:** Supports Guest login and Google login via Supabase. State is maintained via `auth.js`.
|
| 39 |
+
- **Extension:** Uses isolated `chrome.storage.local/session`. **Does not share sessions** with the website.
|
| 40 |
+
- **Priority:** **High**. Users cannot access their cloud documents or synced preferences from the extension.
|
| 41 |
+
|
| 42 |
+
### AI Features
|
| 43 |
+
- **Website:** Full suite (Analyze, Summarize, AutoComplete, Dialect, Quran).
|
| 44 |
+
- **Extension:** Only uses `/api/analyze` (Correct) and `/api/summarize`. Missing AutoComplete, Dialect, and Quran validation.
|
| 45 |
+
- **Priority:** **Medium**. Core features are present, but advanced features are missing.
|
| 46 |
+
|
| 47 |
+
### Documents
|
| 48 |
+
- **Website:** Full document management (Save, Load, Export PDF/DOCX, Sync Queue).
|
| 49 |
+
- **Extension:** Cannot save, load, or access document history.
|
| 50 |
+
- **Priority:** **High**. Destroys the omnichannel UX.
|
| 51 |
+
|
| 52 |
+
---
|
| 53 |
+
|
| 54 |
+
## 4. Missing Features & Gaps
|
| 55 |
+
|
| 56 |
+
1. **Shared Authentication:** The extension operates anonymously. Needs Supabase integration in `background.js` to share JWTs.
|
| 57 |
+
2. **Missing Editor Tools in Extension:** "Dialect" and "Quran" tabs are missing from the sidepanel.
|
| 58 |
+
3. **AutoComplete in Extension:** The website's ghost-text autocomplete is highly valuable but entirely absent from textareas on the web via the extension.
|
| 59 |
+
|
| 60 |
+
---
|
| 61 |
+
|
| 62 |
+
## 5. Bugs & Architectural Issues Found
|
| 63 |
+
|
| 64 |
+
1. **Duplicated Logic:** UI rendering logic for suggestion cards is duplicated between `src/js/ui.js` (website) and `extension/shared/bayan-ui.js` (extension).
|
| 65 |
+
2. **Cache Consistency:** The extension implements its own LRU cache (`_cache` in `background.js`), whereas the website relies on network or different caching strategies.
|
| 66 |
+
3. **Editor Brittle-ness:** The website relies heavily on DOM-based offset replacements (`setEditorHTML`, `restoreSelection`). Any changes to HTML sanitization risk breaking cursor positions. (Must strictly adhere to "DO NOT break existing editor architecture").
|
| 67 |
+
|
| 68 |
+
---
|
| 69 |
+
|
| 70 |
+
## 6. Security Issues
|
| 71 |
+
|
| 72 |
+
1. **API Exposure:** The Hugging Face endpoints (`/api/*`) are public. If they lack rate-limiting or CORS whitelisting, they are vulnerable to abuse by third parties.
|
| 73 |
+
2. **Token Handling:** The extension uses `chrome.storage.local` which is fine, but since it lacks Supabase RLS context, it cannot securely fetch user documents yet.
|
| 74 |
+
|
| 75 |
+
---
|
| 76 |
+
|
| 77 |
+
## 7. Performance Issues
|
| 78 |
+
|
| 79 |
+
1. **Website:** Bundle size is relatively small due to Vanilla JS, but loading heavy libraries like `mammoth.browser.min.js` and `docx.umd.js` synchronously in `index.html` blocks render. These should be lazy-loaded.
|
| 80 |
+
2. **Extension:** `content-inline.js` attaches listeners to `input`/`keyup` events. If not properly debounced on heavy sites (e.g., Google Docs, WordPress), it can cause severe input lag.
|
| 81 |
+
|
| 82 |
+
---
|
| 83 |
+
|
| 84 |
+
## 8. UX Problems
|
| 85 |
+
|
| 86 |
+
1. **Inconsistent Wording:** The website uses "مستنداتي" (My Documents) while the extension lacks this concept entirely.
|
| 87 |
+
2. **Flow Disconnect:** A user correcting text in the extension cannot save that text to their Bayan account to continue editing on the website later.
|
| 88 |
+
3. **Loading States:** The extension's sidepanel lacks the polished "Focus Mode" and "SVG Donut Charts" available on the web editor.
|
| 89 |
+
|
| 90 |
+
---
|
| 91 |
+
|
| 92 |
+
## 9. Technical Debt
|
| 93 |
+
|
| 94 |
+
1. **Separation of Concerns:** The website's JS files (e.g., `editor.js`, `format.js`) tightly couple DOM manipulation with business logic.
|
| 95 |
+
2. **Extension Architecture:** The extension duplicates `constants.js`, `hash.js`, and `analysis-controller.js` instead of importing from a shared monorepo workspace package.
|
| 96 |
+
|
| 97 |
+
---
|
| 98 |
+
|
| 99 |
+
## 10. Recommended Roadmap (Prioritized)
|
| 100 |
+
|
| 101 |
+
### Phase 1: Authentication Unification (Critical)
|
| 102 |
+
- **Goal:** Share Supabase session between Website and Extension.
|
| 103 |
+
- **Action:** Implement `chrome.cookies` or message passing to inject the Supabase JWT into the extension.
|
| 104 |
+
|
| 105 |
+
### Phase 2: Document Sync in Extension (High)
|
| 106 |
+
- **Goal:** Allow extension users to save selected text directly to their Bayan documents.
|
| 107 |
+
- **Action:** Add "Save to Bayan" in the context menu and sidepanel, hitting the Supabase DB.
|
| 108 |
+
|
| 109 |
+
### Phase 3: Parity of AI Tools (Medium)
|
| 110 |
+
- **Goal:** Bring AutoComplete, Dialect, and Quran features to the extension.
|
| 111 |
+
- **Action:** Update the sidepanel UI and `background.js` routing to support `/api/dialect` and `/api/quran`.
|
| 112 |
+
|
| 113 |
+
### Phase 4: Performance & Code Sharing (Low)
|
| 114 |
+
- **Goal:** Reduce tech debt.
|
| 115 |
+
- **Action:** Refactor `shared/` folder to act as a true submodule for both web and extension. Lazy load heavy vendor scripts on the web.
|