swadhin / opengrammar public

chore: Repository documentation cleanup and rewrite

Swadhin Biswas committed 7 months ago
bc27d51
1 parent 137ee96
commit bc27d51
18 files changed
+54 -4131
Showing 18 changed files+54-4004
README.mdopengrammar/FEATURES_IMPLEMENTATION.mdopengrammar/GRAMMARLY_CLONE.mdopengrammar/GROQ_SETUP.mdopengrammar/IMPROVEMENTS.mdopengrammar/PRODUCTION.mdopengrammar/SELF_HOSTING.mdopengrammar/SETUP_GUIDE.mdopengrammar/TESTING_GUIDE.mdopengrammar/TEST_GRAMMARLY_STYLE.mdopengrammar/TROUBLESHOOTING.mdopengrammar/WHATS_NEW.mdopengrammar/backend/.gitignoreopengrammar/backend/MULTI_PLATFORM.mdopengrammar/backend/RAILWAY_DEPLOYMENT.mdopengrammar/backend/README.npm.mdopengrammar/backend/RENDER_DEPLOYMENT.mdopengrammar/backend/VERCEL_DEPLOYMENT.md
▼README.md
+53-63
@@ -7,105 +7,95 @@
7
7
*The completely free, zero-compromise Grammarly alternative you can host yourself.*
8
8
9
9
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
10
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
11
- [![React](https://img.shields.io/badge/React-20232A?style=flat-square&logo=react&logoColor=61DAFB)](https://reactjs.org/)
12
- [![Vite](https://img.shields.io/badge/vite-%23646CFF.svg?style=flat-square&logo=vite&logoColor=white)](https://vitejs.dev/)
10
+ [![NPM Package](https://img.shields.io/npm/v/opengrammar-server)](https://www.npmjs.com/package/opengrammar-server)
11
+ [![Docker Pulls](https://img.shields.io/docker/pulls/swadhinbiswas/opengrammar-backend)](https://hub.docker.com/r/swadhinbiswas/opengrammar-backend)
12
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
13
+
14
+ 🌐 **[Official Website](https://opengrammer.eu.cc)** | 📖 **[Documentation](https://opengrammer.eu.cc/docs)**
13
15
</div>
14
16
15
17
---
16
18
17
19
Writing clearly matters. But achieving perfect grammar shouldn't mean sacrificing your privacy or paying a premium monthly subscription to a tech giant.
18
20
19
-Welcome to **OpenGrammar**—a powerful, robust browser extension built from the ground up to match the premium writing tools you already know, but with one massive difference: **You own your data, and it runs completely for free.**
21
+**OpenGrammar** is a powerful, robust intelligent writing assistant built from the ground up to match the premium writing tools you already know, but with one massive difference: **You own your data, and it runs completely for free.**
20
22
21
23
## 🌟 Why OpenGrammar?
22
24
23
-For too long, the industry standard has been to quietly siphon every keystroke you type to remote servers, locking advanced features behind hefty paywalls. OpenGrammar is our answer to that:
24
-
25
25
1. **The Zero-Cost Foundation:** Out of the box, our core engine runs 100% locally in your browser. With a massive 156,000-word offline dictionary, it instantly catches misspellings, passive voice, and weak phrasing without ever pinging a server.
26
-2. **Bring Your Own Brain (BYOK):** Want deep, context-aware AI corrections? Just plug in your own API key (OpenAI, Groq, Together, OpenRouter, or even local open-source models via Ollama). You pay fractions of a cent exclusively for what you use, cutting out the middleman entirely.
27
-3. **Paranoid-Level Privacy:** We don't have a database. We don't want your user data. Your API key never leaves your browser storage. If you choose to use the AI features, your text is processed through a stateless edge function and immediately deleted.
28
-4. **Deploy It Yourself:** Trust no one? Perfect. You can deploy our lightweight backend to Cloudflare Workers or Vercel Edge for free, in a single command. You own the entire pipeline.
26
+2. **Bring Your Own Brain (BYOK):** Want deep, context-aware AI corrections? Just plug in your own API key (OpenAI, Groq, Together, OpenRouter, or even local models via Ollama). You pay fractions of a cent exclusively for what you use.
27
+3. **Paranoid-Level Privacy:** We don't have a database. We don't want your user data. Your API key never leaves your browser storage. Text processed through the AI is immediately deleted via stateless edge functions.
28
+4. **Deploy It Yourself:** You own the entire pipeline. Host our lightweight backend instantly via Docker, npm, Cloudflare, Vercel, or Netlify.
29
29
30
-## ✨ Under The Hood
31
-
32
-OpenGrammar 2.0 isn't just a wrapper—it's a dual-engine powerhouse.
30
+---
33
31
34
-- **Blazing Fast & Works Everywhere:** We seamlessly inject directly into text inputs, textareas, and complex rich-text editors (Gmail, Google Docs, Notion, Reddit). Built on React, Vite, and Manifest V3 so it never bogs down your browser.
35
-- **The Dual-Engine Architecture:**
36
- 1. *The Offline Sentinel:* A Damerau-Levenshtein edit-distance and phonetic matching spellchecker catches immediate typos. 40+ granular grammar rules instantly flag subject-verb agreement issues, sentence fragments, and commonly confused words (like affect/effect).
37
- 2. *The AI Enforcer:* An intelligent LLM router. Thanks to our **Deduplication Logic**, the AI is completely aware of what the Offline Sentinel already caught. It *never* wastes expensive tokens repeating basic fixes.
38
-- **Smart Context Awareness:** Are you writing a casual tweet, a highly technical documentation page, or a formal business email? The engine automatically detects your domain and scales its strictness appropriately.
39
-- **Deep Analytics & History:**
40
- - **Dynamic Writing Score:** Evaluates your text dynamically from 0-100 based on your Correctness, Readability, Engagement (vocabulary diversity), and Sentence Delivery variation.
41
- - **Private Daily Tracking:** Silently logs your writing history, words checked, and average daily score directly to your local extension storage.
42
-- **Tone & Style Rewriting:** Right-click context menus or a quick `Ctrl+Shift+R` to instantly rethink highlighted text into 8 different tones.
43
-- **Flawless UI:** The classic red, yellow, and blue squiggly underlines you grew up with, paired with slick, interactive click-to-apply tooltips and a gorgeous stats dashboard.
32
+## 🚀 Live Production Endpoints
44
33
45
-## 🚀 Getting Started (For Users)
34
+Don't want to host the backend yourself? OpenGrammar comes with incredibly fast, globally-distributed public edge deployments that you can connect your browser extension to instantly:
46
35
47
-*Note: As an open-source tool in active development, OpenGrammar is currently installed via developer mode.*
36
+- ☁️ **Cloudflare Workers:** [`https://cf.opengrammer.eu.cc/`](https://cf.opengrammer.eu.cc/)
37
+- △ **Vercel Edge:** [`https://vercel.opengrammer.eu.cc/`](https://vercel.opengrammer.eu.cc/)
38
+- 🟩 **Netlify Functions:** [`https://nl.opengrammer.eu.cc/`](https://nl.opengrammer.eu.cc/)
48
39
49
-1. **Download the Extension:** Grab the latest release or clone this repository.
50
-2. **Open Extensions Page:** In Chrome/Brave/Edge, navigate to `chrome://extensions/`.
51
-3. **Enable Developer Mode:** Toggle the switch in the top right corner.
52
-4. **Load Unpacked:** Click the "Load unpacked" button and select the `opengrammar/extension/dist` folder you built or downloaded.
53
-5. **Configure:** Click the OpenGrammar feather icon in your browser toolbar. Paste in your OpenAI, Groq, or OpenRouter API key to unlock the advanced AI engine.
40
+---
54
41
55
-## 💻 Developer Guide: Build & Deploy
42
+## 🛠️ Installation & Self-Hosting
56
43
57
-Want to build OpenGrammar from scratch or deploy your own serverless backend? Let's get to it.
44
+Our backend is natively multi-platform. Choose the environment that best fits your workflow.
58
45
59
-### Prerequisites
46
+### 📦 Option 1: NPM / Mobile / Node Environments
47
+Run the OpenGrammar server on any machine with Node.js. You can effortlessly run this on an old laptop, a VPS, or even an Android phone using Termux!
60
48
61
-- Node.js (v18 or newer)
62
-- [Bun](https://bun.sh/) (Highly Recommended) or npm/pnpm
49
+```bash
50
+# Run instantly without installing
51
+npx opengrammar-server
63
52
64
-### 1. Set up the Backend (Serverless Edge API)
53
+# Or install globally for persistent usage
54
+npm install -g opengrammar-server
55
+opengrammar-server --port 8787
56
+```
65
57
66
-Our backend isn't a bloated server. It's an ultra-lightweight Hono API that securely masks and handles AI routing.
58
+### 🐳 Option 2: Docker
59
+We maintain a highly optimized, multi-architecture Docker image. This is the recommended route for standard server environments or local homelabs.
67
60
68
61
```bash
69
-# Navigate to the backend folder
70
-cd opengrammar/backend
71
-
72
-# Install dependencies lightning fast with Bun
73
-bun install
62
+# Pull the production image
63
+docker pull swadhinbiswas/opengrammar-backend:latest
74
64
75
-# Run locally for testing (runs on http://localhost:8787)
76
-bun run dev
77
-
78
-# Deploy globally to Cloudflare Workers (requires a free Cloudflare account)
79
-bun run deploy
65
+# Run the container (exposes port 8787)
66
+docker run -d -p 8787:8787 --name opengrammar swadhinbiswas/opengrammar-backend:latest
80
67
```
81
68
82
-### 2. Set up the Chrome Extension
69
+### 🧩 Option 3: Browser Extension (For Users)
83
70
84
-```bash
85
-# Navigate to the extension folder
86
-cd opengrammar/extension
71
+1. Download the latest release from the `opengrammar/extension/dist` build.
72
+2. Open Chrome/Brave/Edge and navigate to `chrome://extensions/`.
73
+3. Enable **Developer Mode**.
74
+4. Click **Load unpacked** and select the extension folder.
75
+5. Click the OpenGrammar feather icon in your toolbar, input your custom AI API keys, and link it to one of the **Live Production Endpoints** listed above!
87
76
88
-# Install dependencies
89
-bun install
77
+---
90
78
91
-# Build the extension into an optimized bundle
92
-bun run build
93
-```
79
+## ✨ Core Features
94
80
95
-The build process will generate a `dist/` folder. Load this folder into your browser following the user instructions above!
81
+- **The Dual-Engine Architecture:** A blazing fast local (offline) RegEx + Dictionary matching engine, paired securely with a configurable LLM router framework for tone rewriting and smart context adjustments.
82
+- **Deduplication Logic:** The AI is fully synchronized with the local spellchecker. It never wastes expensive AI tokens re-checking typos already caught locally.
83
+- **Smart Context Awareness:** Automatically detects if you are writing a casual tweet, a technical document, or a formal business email, scaling its strictness appropriately.
84
+- **Dynamic Writing Score:** Evaluates your text dynamically (0-100) based on Correctness, Readability, Engagement, and Sentence Delivery.
85
+- **Flawless Integrations:** Securely injects into rich-text editors including Gmail, Google Docs, Notion, and Reddit.
86
+
87
+---
96
88
97
89
## 🤝 Join the Rebellion
98
90
99
91
**We need your help to unseat the monopolies and make OpenGrammar the definitive open-source writing assistant.**
100
92
101
-Our biggest mission right now is building the ultimate library of local (offline) grammar and style rules. You don't even need to be a software engineer to contribute—if you're a language nerd with a good eye for grammar, we want you!
102
-
103
-- **📚 Add Grammar Rules:** Help us expand `analyzer.ts` with more regex-based rules for common mistakes, style improvements, and clarity checks. See our [GRAMMAR_RULES.md](./GRAMMAR_RULES.md) guide.
104
-- **🐛 Hunt Bugs:** Found a weird website where the text highlighting breaks? Open an issue.
105
-- **💡 Dream Up Features:** Have an idea for something cool? Start a thread in our Discussions tab.
93
+Whether you are a TypeScript developer wanting to optimize edge latency, or a language nerd looking to build out our offline Regex `GRAMMAR_RULES.md`—we want you!
106
94
107
-Check out our [CONTRIBUTING.md](./CONTRIBUTING.md) and peek at the `ROADMAP.md` to see where we're headed next.
95
+- Read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide.
96
+- Check our `ROADMAP.md` to see what we are currently building.
97
+- Open an issue for bugs or start a thread in our Discussions tab.
108
98
109
99
## 📄 License
110
100
111
-This project is open-source and proudly licensed under the Apache 2.0 License. See the LICENSE file for details. Let's build the future of writing together.
101
+This project is proudly open-source under the **Apache 2.0 License**. See the `LICENSE` file for details. Let's build the future of writing together.
112
102
▼opengrammar/FEATURES_IMPLEMENTATION.md
+0-451
@@ -1,464 +0,0 @@
1
-# 🚀 OpenGrammar Feature Implementation Guide
2
-
3
-This document provides implementation details for Phase 2, 3, and 4 features.
4
-
5
-
6
-## ✅ Phase 2: Enhanced UX (Completed)
7
-
8
-### 1. Tone & Style Adjustments ✓
9
-**Status:** Implemented
10
-**Files:** `extension/src/rewrite/`
11
-
12
-**Features:**
13
-- 8 tone options (formal, casual, professional, friendly, concise, detailed, persuasive, neutral)
14
-- Context menu integration (right-click → Rewrite)
15
-- Keyboard shortcut (Ctrl+Shift+R)
16
-- Side-by-side comparison UI
17
-- Apply/Copy buttons
18
-
19
-**Usage:**
20
-```javascript
21
-// Select text → Right-click → "Rewrite with OpenGrammar"
22
-// Or press Ctrl+Shift+R
23
-```
24
-
25
-### 2. Writing Statistics ✓
26
-**Status:** Implemented
27
-**Files:** `extension/src/stats/`
28
-
29
-**Metrics:**
30
-- Word count, character count, sentence count, paragraph count
31
-- Flesch Reading Ease Score
32
-- Flesch-Kincaid Grade Level
33
-- Automated Readability Index (ARI)
34
-- Vocabulary diversity
35
-- Reading/speaking time estimates
36
-- Issue breakdown by type
37
-
38
-**Usage:**
39
-```javascript
40
-// Access via popup → Statistics tab
41
-// Or future: keyboard shortcut
42
-```
43
-
44
-### 3. Custom Prompts for AI ✓
45
-**Status:** Implemented (Library)
46
-**Files:** `extension/src/prompts/`
47
-
48
-**Preset Prompts:**
49
-- Fix Grammar
50
-- Make Formal/Casual
51
-- Simplify
52
-- Expand
53
-- Summarize
54
-- British English
55
-- Persuade
56
-
57
-**Next Steps:**
58
-- Add UI for prompt selection in rewrite popup
59
-- Allow users to create custom prompts
60
-- Save favorite prompts to storage
61
-
62
-
63
-## 🔨 Phase 3: Advanced Features (Implementation Guide)
64
-
65
-### 4. Better Google Docs Support
66
-
67
-**Implementation Steps:**
68
-
69
-1. **Create Google Docs-specific content script:**
70
-```typescript
71
-// extension/src/content/google-docs.ts
72
-export class GoogleDocsHandler {
73
- private editorElement: HTMLElement | null = null;
74
-
75
- findEditor() {
76
- // Google Docs uses a complex iframe structure
77
- const iframe = document.querySelector('.docs-texteventtarget-iframe');
78
- if (iframe) {
79
- const doc = (iframe as HTMLIFrameElement).contentDocument;
80
- this.editorElement = doc?.querySelector('.kix-appview-editor');
81
- }
82
- }
83
-
84
- extractText() {
85
- // Google Docs stores content in paragraph spans
86
- const paragraphs = this.editorElement?.querySelectorAll('.kix-paragraphrenderer');
87
- return Array.from(paragraphs || []).map(p => p.textContent).join('\n');
88
- }
89
-}
90
-```
91
-
92
-2. **Update manifest for iframe access:**
93
-```json
94
-"content_scripts": [
95
- {
96
- "matches": ["https://docs.google.com/*"],
97
- "js": ["src/content/google-docs.ts"],
98
- "all_frames": true
99
- }
100
-]
101
-```
102
-
103
-3. **Handle Google Docs-specific events:**
104
-- Listen for `docs-chapter-renderer` events
105
-- Monitor selection changes in iframe
106
-- Position highlights relative to editor viewport
107
-
108
-**Estimated Effort:** 2-3 days
109
-
110
-
111
-### 5. Autocomplete & Prediction
112
-
113
-**Implementation:**
114
-
115
-1. **Add autocomplete API endpoint:**
116
-```typescript
117
-// backend/src/index.ts
118
-app.post('/autocomplete', async (c) => {
119
- const { text, cursor, apiKey, model } = await c.req.json();
120
-
121
- // Get last 50 characters before cursor
122
- const context = text.substring(Math.max(0, cursor - 50), cursor);
123
-
124
- const prompt = `Continue this text naturally (max 20 words):
125
-
126
-Context: ${context}...
127
-
128
-Continuation:`;
129
-
130
- // Call LLM with max_tokens=20
131
- const completion = await openai.chat.completions.create({
132
- messages: [{ role: 'user', content: prompt }],
133
- model,
134
- max_tokens: 20,
135
- temperature: 0.8,
136
- });
137
-
138
- return c.json({
139
- suggestion: completion.choices[0].message.content?.trim(),
140
- });
141
-});
142
-```
143
-
144
-2. **Add content script autocomplete UI:**
145
-```typescript
146
-// extension/src/content/autocomplete.ts
147
-export class AutocompletePopup {
148
- private popup: HTMLElement | null = null;
149
-
150
- showSuggestion(suggestion: string, position: { top: number; left: number }) {
151
- this.popup = document.createElement('div');
152
- this.popup.className = 'opengrammar-autocomplete';
153
- this.popup.innerHTML = `
154
- <span class="ghost-text">${text}</span>
155
- <span class="suggestion">${suggestion}</span>
156
- `;
157
- // Position at cursor
158
- }
159
-
160
- accept() {
161
- // Insert suggestion at cursor
162
- }
163
-}
164
-```
165
-
166
-3. **Debounce API calls (300ms after typing stops)**
167
-
168
-**Estimated Effort:** 3-4 days
169
-
170
-
171
-### 6. Contextual Understanding
172
-
173
-**Implementation:**
174
-
175
-1. **Add context window to analysis:**
176
-```typescript
177
-// backend/src/analyzer.ts
178
-export async function analyzeWithContext(
179
- text: string,
180
- context: {
181
- previousParagraphs: string[];
182
- documentType?: string;
183
- tone?: string;
184
- }
185
-) {
186
- const prompt = `Analyze this text considering the context:
187
-
188
-Previous context: ${context.previousParagraphs.join(' ')}
189
-Document type: ${context.documentType || 'general'}
190
-
191
-Text to analyze: ${text}
192
-
193
-Consider consistency with previous content and overall tone.`;
194
-
195
- // Call LLM with context
196
-}
197
-```
198
-
199
-2. **Store document context in background:**
200
-```typescript
201
-// extension/src/background/index.ts
202
-const documentContexts = new Map<string, {
203
- text: string;
204
- timestamp: number;
205
- tone?: string;
206
-}>();
207
-
208
-// Keep last 5000 characters per domain
209
-chrome.tabs.onActivated.addListener((tab) => {
210
- // Load context for this tab
211
-});
212
-```
213
-
214
-**Estimated Effort:** 2-3 days
215
-
216
-
217
-### 7. Reading Time Estimates ✓
218
-**Status:** Already implemented in Writing Statistics
219
-
220
-**Current Features:**
221
-- Reading time (200 wpm)
222
-- Speaking time (150 wpm)
223
-
224
-**Enhancements:**
225
-- Add detailed breakdown (by paragraph)
226
-- Show progress indicator while reading
227
-- Add customizable reading speed
228
-
229
-
230
-### 8. Vocabulary Diversity Metrics ✓
231
-**Status:** Already implemented in Writing Statistics
232
-
233
-**Current Features:**
234
-- Unique word count
235
-- Vocabulary diversity percentage
236
-- Average word length
237
-
238
-**Enhancements:**
239
-- Track most used words
240
-- Suggest synonyms for overused words
241
-- Show vocabulary level (basic, intermediate, advanced)
242
-
243
-
244
-## 🌐 Phase 4: Expansion (Implementation Guide)
245
-
246
-### 9. Firefox Support
247
-
248
-**Steps:**
249
-
250
-1. **Create Firefox-specific manifest:**
251
-```json
252
-// extension/manifest-firefox.json
253
-{
254
- "browser_specific_settings": {
255
- "gecko": {
256
- "id": "[email protected]",
257
- "strict_min_version": "109.0"
258
- }
259
- },
260
- // Rest same as Chrome manifest
261
-}
262
-```
263
-
264
-2. **Adjust Chrome-specific APIs:**
265
-```typescript
266
-// Use browser polyfill
267
-import browser from 'webextension-polyfill';
268
-
269
-// Replace chrome.* with browser.*
270
-browser.storage.sync.get(...);
271
-browser.contextMenus.create(...);
272
-```
273
-
274
-3. **Add Firefox build script:**
275
-```json
276
-// package.json
277
-"scripts": {
278
- "build:firefox": "vite build --mode firefox"
279
-}
280
-```
281
-
282
-4. **Test in Firefox:**
283
-- Load temporary add-on in about:debugging
284
-- Submit to Firefox Add-ons
285
-
286
-**Estimated Effort:** 1-2 days
287
-
288
-
289
-### 10. Safari Support
290
-
291
-**Steps:**
292
-
293
-1. **Use Xcode to create Safari Web Extension:**
294
-```bash
295
-xcrun safari-web-extension-converter extension/dist/ \
296
- --project-location ./safari \
297
- --bundle-identifier com.opengrammar.safari
298
-```
299
-
300
-2. **Adjust manifest for Safari:**
301
-- Some Chrome APIs not supported
302
-- May need native app for full functionality
303
-
304
-3. **Create macOS app wrapper:**
305
-- Swift app to host extension
306
-- Notarize for App Store distribution
307
-
308
-**Estimated Effort:** 3-5 days
309
-
310
-
311
-### 11. Desktop Apps
312
-
313
-**Implementation:**
314
-
315
-1. **Use Electron for cross-platform desktop app:**
316
-```bash
317
-npm install electron
318
-```
319
-
320
-2. **Create Electron main process:**
321
-```typescript
322
-// desktop/main.ts
323
-import { app, BrowserWindow } from 'electron';
324
-
325
-function createWindow() {
326
- const win = new BrowserWindow({
327
- width: 800,
328
- height: 600,
329
- webPreferences: {
330
- nodeIntegration: true,
331
- },
332
- });
333
-
334
- win.loadURL('https://opengrammar.app');
335
-}
336
-
337
-app.whenReady().then(createWindow);
338
-```
339
-
340
-3. **Integrate with system-wide text inputs:**
341
-- Use native messaging for system-wide support
342
-- Create keyboard shortcut for global access
343
-
344
-**Estimated Effort:** 5-7 days
345
-
346
-
347
-### 12. Developer API
348
-
349
-**Implementation:**
350
-
351
-1. **Add API key management:**
352
-```typescript
353
-// backend/src/index.ts
354
-app.post('/api/v1/analyze', async (c) => {
355
- const apiKey = c.req.header('Authorization')?.replace('Bearer ', '');
356
-
357
- // Validate API key against database
358
- const user = await validateApiKey(apiKey);
359
- if (!user) {
360
- return c.json({ error: 'Invalid API key' }, 401);
361
- }
362
-
363
- // Process request
364
- const { text } = await c.req.json();
365
- const issues = RuleBasedAnalyzer.analyze(text);
366
-
367
- return c.json({ issues });
368
-});
369
-```
370
-
371
-2. **Add rate limiting:**
372
-```typescript
373
-import { rateLimit } from 'hono-rate-limit';
374
-
375
-app.use('/api/*', rateLimit({
376
- windowMs: 60 * 1000, // 1 minute
377
- max: 100, // 100 requests per minute
378
-}));
379
-```
380
-
381
-3. **Create API documentation:**
382
-```markdown
383
-# OpenGrammar API
384
-
385
-## POST /api/v1/analyze
386
-
387
-Analyze text for grammar and style issues.
388
-
389
-### Request
390
-```json
391
-{
392
- "text": "string",
393
- "options": {
394
- "checkGrammar": true,
395
- "checkStyle": true
396
- }
397
-}
398
-```
399
-
400
-### Response
401
-```json
402
-{
403
- "issues": [...],
404
- "metadata": {...}
405
-}
406
-```
407
-```
408
-
409
-4. **Add SDK packages:**
410
-```bash
411
-npm publish @opengrammar/js
412
-pip publish opengrammar
413
-```
414
-
415
-**Estimated Effort:** 3-4 days
416
-
417
-
418
-## 📊 Priority & Timeline
419
-
420
-| Feature | Priority | Effort | Dependencies |
421
-|---------|----------|--------|--------------|
422
-| Google Docs Support | High | 2-3 days | None |
423
-| Autocomplete | High | 3-4 days | None |
424
-| Firefox Support | Medium | 1-2 days | None |
425
-| Developer API | Medium | 3-4 days | Backend updates |
426
-| Contextual Understanding | Medium | 2-3 days | Storage updates |
427
-| Desktop Apps | Low | 5-7 days | None |
428
-| Safari Support | Low | 3-5 days | macOS required |
429
-
430
-**Total Estimated Effort:** 19-28 days
431
-
432
-
433
-## 🎯 Next Steps
434
-
435
-1. **Immediate (Week 1):**
436
- - [ ] Add UI for custom prompts in rewrite popup
437
- - [ ] Implement Google Docs support
438
- - [ ] Add autocomplete feature
439
-
440
-2. **Short-term (Week 2-3):**
441
- - [ ] Build Firefox extension
442
- - [ ] Add contextual understanding
443
- - [ ] Create developer API
444
-
445
-3. **Long-term (Month 2+):**
446
- - [ ] Build desktop apps
447
- - [ ] Safari extension
448
- - [ ] Advanced AI features
449
-
450
-
451
-**Contributing:** Pick a feature from the list above and create a PR! Each feature includes implementation details to get you started.
452
0
▼opengrammar/GRAMMARLY_CLONE.md
+0-328
@@ -1,339 +0,0 @@
1
-# 🎯 OpenGrammar vs Grammarly - Exact Feature Comparison
2
-
3
-## ✅ OpenGrammar IS Now a Grammarly Clone!
4
-
5
-OpenGrammar uses the **same hybrid approach** as Grammarly:
6
-
7
-```
8
-Grammarly = Rule-based + AI
9
-OpenGrammar = Rule-based + AI ✅
10
-```
11
-
12
-
13
-## 📊 Feature-by-Feature Comparison
14
-
15
-| Feature | Grammarly | OpenGrammar | Status |
16
-|---------|-----------|-------------|--------|
17
-| **Rule-Based Checking** | ✅ | ✅ | ✅ Complete |
18
-| **AI-Powered Checking** | ✅ | ✅ | ✅ Complete |
19
-| **Spelling Correction** | ✅ | ✅ (100+ words) | ✅ Complete |
20
-| **Basic Grammar** | ✅ | ✅ (35+ rules) | ✅ Complete |
21
-| **Punctuation** | ✅ | ✅ | ✅ Complete |
22
-| **Tone Detection** | ✅ | ✅ (8 tones) | ✅ Complete |
23
-| **Style Suggestions** | ✅ | ✅ | ✅ Complete |
24
-| **Sentence Rewriting** | ✅ | ✅ | ✅ Complete |
25
-| **Context Understanding** | ✅ | ✅ (LLM-based) | ✅ Complete |
26
-| **Passive Voice** | ✅ | ✅ | ✅ Complete |
27
-| **Readability Scores** | ✅ | ✅ (Flesch, ARI) | ✅ Complete |
28
-| **Word Count** | ✅ | ✅ | ✅ Complete |
29
-| **Reading Time** | ✅ | ✅ | ✅ Complete |
30
-| **Vocabulary Analysis** | ✅ | ✅ | ✅ Complete |
31
-| **Custom Dictionary** | ✅ | ✅ | ✅ Complete |
32
-| **Ignore Suggestions** | ✅ | ✅ | ✅ Complete |
33
-| **Multi-Platform** | ✅ | ✅ (Chrome + more) | ✅ Complete |
34
-| **Privacy-First** | ❌ | ✅ | ✅ Better! |
35
-| **Free** | ❌ (Freemium) | ✅ (100% Free) | ✅ Better! |
36
-| **Open Source** | ❌ | ✅ | ✅ Better! |
37
-| **Self-Hostable** | ❌ | ✅ | ✅ Better! |
38
-| **Multiple AI Providers** | ❌ | ✅ (6 providers) | ✅ Better! |
39
-| **Local LLM Support** | ❌ | ✅ (Ollama) | ✅ Better! |
40
-
41
-
42
-## 🔧 How OpenGrammar Matches Grammarly
43
-
44
-### 1️⃣ Rule-Based System (Like Grammarly)
45
-
46
-**Grammarly's Approach:**
47
-- Uses traditional grammar rules
48
-- Fast, works offline
49
-- Catches basic errors instantly
50
-
51
-**OpenGrammar's Implementation:**
52
-```typescript
53
-// 140+ rule-based checks
54
-✅ checkBasicGrammar() - 35+ grammar rules
55
-✅ checkCommonMisspellings() - 100+ words
56
-✅ checkPassiveVoice()
57
-✅ checkRepetition()
58
-✅ checkSpacingErrors()
59
-✅ checkApostropheErrors()
60
-✅ checkPunctuation()
61
-✅ checkLongSentences()
62
-✅ checkDoubleNegatives()
63
-✅ checkRedundantPhrases()
64
-✅ checkWeakWords()
65
-✅ checkCliches()
66
-```
67
-
68
-**Examples:**
69
-```
70
-Input: "me and him went and buyed milks"
71
-
72
-Rule-based detects:
73
-❌ "me and him" → "he and I" (pronoun error)
74
-❌ "buyed" → "bought" (irregular verb)
75
-
76
-✅ Works WITHOUT AI - instant & free!
77
-```
78
-
79
-
80
-### 2️⃣ AI-Powered System (Like Grammarly)
81
-
82
-**Grammarly's Approach:**
83
-- Uses machine learning models
84
-- Understands context
85
-- Provides advanced suggestions
86
-- Detects tone and style
87
-
88
-**OpenGrammar's Implementation:**
89
-```typescript
90
-// Multi-provider AI support
91
-✅ Groq (Llama 3.1 70B) - Fast & Free
92
-✅ OpenAI (GPT-4, GPT-3.5) - Best quality
93
-✅ OpenRouter (100+ models)
94
-✅ Together AI (Open source)
95
-✅ Ollama (Local LLM) - Offline & Private
96
-✅ Custom endpoints
97
-
98
-// AI handles:
99
-✅ Advanced grammar
100
-✅ Context understanding
101
-✅ Tone suggestions
102
-✅ Style improvements
103
-✅ Sentence rewriting
104
-```
105
-
106
-**Examples:**
107
-```
108
-Input: "The report was written by John yesterday"
109
-
110
-AI detects:
111
-⚠️ Passive voice → "John wrote the report yesterday"
112
-💡 Style suggestion → More direct and clear
113
-
114
-✅ Contextual understanding!
115
-```
116
-
117
-
118
-### 3️⃣ Hybrid System (Grammarly's Secret)
119
-
120
-**How Grammarly Works:**
121
-```
122
-User types → Rule check (instant) → AI check (contextual) → Combine results → Show suggestions
123
-```
124
-
125
-**How OpenGrammar Works:**
126
-```typescript
127
-// Exact same hybrid approach!
128
-app.post('/analyze', async (c) => {
129
- // 1. Rule-based (instant, free)
130
- let issues = RuleBasedAnalyzer.analyze(text);
131
-
132
- // 2. AI-powered (contextual, smart)
133
- if (apiKey || provider === 'ollama') {
134
- const llmIssues = await LLMAnalyzer.analyze(text, apiKey, model, provider);
135
- issues = [...issues, ...llmIssues];
136
- }
137
-
138
- // 3. Return combined results
139
- return { issues };
140
-});
141
-```
142
-
143
-**Result:**
144
-- ✅ Fast rule-based catches simple errors
145
-- ✅ Smart AI catches complex issues
146
-- ✅ Best of both worlds!
147
-
148
-
149
-## 🎯 Grammarly Features We've Cloned
150
-
151
-### ✅ Spelling & Grammar
152
-- [x] Common misspellings (100+ words)
153
-- [x] Basic grammar rules (35+ rules)
154
-- [x] Irregular verbs (buyed → bought)
155
-- [x] Pronoun errors (me and him → he and I)
156
-- [x] Subject-verb agreement
157
-- [x] Punctuation
158
-- [x] Apostrophes
159
-
160
-### ✅ Advanced Writing
161
-- [x] Passive voice detection
162
-- [x] Sentence length analysis
163
-- [x] Readability scores (Flesch, ARI)
164
-- [x] Redundant phrases
165
-- [x] Weak words
166
-- [x] Clichés
167
-
168
-### ✅ Tone & Style
169
-- [x] 8 tone options (Formal, Casual, Professional, etc.)
170
-- [x] Tone rewriting
171
-- [x] Style suggestions
172
-- [x] Sentence improvement
173
-
174
-### ✅ Smart Features
175
-- [x] Context understanding
176
-- [x] Vocabulary diversity
177
-- [x] Reading time estimates
178
-- [x] Word/sentence/paragraph counts
179
-- [x] Custom dictionary
180
-- [x] Ignore suggestions
181
-
182
-### ✅ User Experience
183
-- [x] Real-time checking
184
-- [x] Click-to-apply suggestions
185
-- [x] Interactive tooltips
186
-- [x] Color-coded highlights
187
-- [x] Works everywhere on web
188
-
189
-
190
-## 🚀 OpenGrammar Advantages Over Grammarly
191
-
192
-| Feature | Grammarly | OpenGrammar |
193
-|---------|-----------|-------------|
194
-| **Cost** | $12/month for premium | 100% Free |
195
-| **Privacy** | Sends all data to servers | Your data stays local |
196
-| **AI Choice** | Only Grammarly's AI | Choose from 6+ providers |
197
-| **Offline** | Limited | Full offline with Ollama |
198
-| **Customization** | Limited | Fully customizable |
199
-| **Self-Hosting** | No | Yes (Docker, Cloudflare) |
200
-| **Open Source** | No | Yes |
201
-| **API Access** | Paid API | Free self-hosted API |
202
-
203
-
204
-## 📦 What's Included
205
-
206
-### Backend (Serverless API)
207
-```
208
-✅ Rule-based analyzer (140+ rules)
209
-✅ AI analyzer (6 providers)
210
-✅ Hybrid checking system
211
-✅ Tone rewriting API
212
-✅ Statistics/metrics API
213
-✅ Health monitoring
214
-✅ Docker support
215
-```
216
-
217
-### Extension (Chrome)
218
-```
219
-✅ Real-time grammar checking
220
-✅ Interactive tooltips
221
-✅ Click-to-apply
222
-✅ Multi-provider selection
223
-✅ Tone rewriting popup
224
-✅ Statistics dashboard
225
-✅ Options page
226
-✅ Custom dictionary
227
-✅ Ignore functionality
228
-```
229
-
230
-### Documentation
231
-```
232
-✅ README.md - Getting started
233
-✅ TESTING_GUIDE.md - How to test
234
-✅ GROQ_SETUP.md - Groq API setup
235
-✅ SELF_HOSTING.md - Docker deployment
236
-✅ PRODUCTION.md - Production guide
237
-✅ TROUBLESHOOTING.md - Fix common issues
238
-✅ FEATURES_IMPLEMENTATION.md - Feature details
239
-✅ GRAMMARLY_CLONE.md - This file!
240
-```
241
-
242
-
243
-## 🎯 How to Use (Grammarly-Style)
244
-
245
-### 1. Install Extension
246
-```
247
-1. Build: cd extension && npm run build
248
-2. Load: chrome://extensions/ → Load unpacked → dist/
249
-3. Click icon → Configure settings
250
-```
251
-
252
-### 2. Configure (Choose Your Mode)
253
-
254
-**Mode A: Free + Offline (Rule-based only)**
255
-```
256
-- No API key needed
257
-- Works offline
258
-- Catches basic errors
259
-- Instant results
260
-```
261
-
262
-**Mode B: Free + Smart (Groq free tier)**
263
-```
264
-- Get free Groq key: console.groq.com
265
-- 100 requests/day free
266
-- Advanced grammar
267
-- Context understanding
268
-```
269
-
270
-**Mode C: Private + Smart (Ollama local)**
271
-```
272
-- Install Ollama
273
-- Pull model: ollama pull qwen2.5:1.5b
274
-- 100% private, offline
275
-- No API costs
276
-```
277
-
278
-**Mode D: Best Quality (OpenAI/GPT-4)**
279
-```
280
-- Use your OpenAI key
281
-- Best grammar detection
282
-- Most accurate suggestions
283
-```
284
-
285
-### 3. Write Like Grammarly
286
-```
287
-1. Open any text box (Gmail, Docs, etc.)
288
-2. Start typing
289
-3. Red underlines = grammar/spelling errors
290
-4. Yellow underlines = clarity issues
291
-5. Blue underlines = style suggestions
292
-6. Click underline → See suggestion → Apply fix
293
-```
294
-
295
-
296
-## ✅ Final Verdict
297
-
298
-**Is OpenGrammar a Grammarly clone?**
299
-
300
-✅ **YES!** OpenGrammar uses the exact same hybrid approach:
301
-- Rule-based for fast, basic errors
302
-- AI-powered for smart, contextual suggestions
303
-- Both working together seamlessly
304
-
305
-**Plus these advantages:**
306
-- 100% Free (no premium tier needed)
307
-- Privacy-first (your data stays yours)
308
-- Open source (customize anything)
309
-- Self-hostable (run your own)
310
-- Multiple AI providers (choose what works best)
311
-- Offline capable (with Ollama)
312
-
313
-
314
-## 🎉 Conclusion
315
-
316
-**Grammarly = Rule-based + AI**
317
-
318
-**OpenGrammar = Rule-based (140+ rules) + AI (6 providers)**
319
-
320
-**OpenGrammar IS a complete Grammarly clone with more freedom and privacy!** 🚀
321
-
322
-
323
-**Ready to use?**
324
-1. Check `TESTING_GUIDE.md` for testing instructions
325
-2. Check `GROQ_SETUP.md` for free AI setup
326
-3. Check `SELF_HOSTING.md` for deployment
327
-
328
-Happy writing! ✨
329
0
▼opengrammar/GROQ_SETUP.md
+0-186
@@ -1,196 +0,0 @@
1
-# 🚀 Quick Start with Groq API
2
-
3
-## Step 1: Get Your Free Groq API Key
4
-
5
-1. Visit: https://console.groq.com
6
-2. Sign up / Log in
7
-3. Go to **API Keys** section
8
-4. Click **Create API Key**
9
-5. Copy your API key (starts with `gsk_`)
10
-
11
-**Free Tier Limits:**
12
-- 100 requests/day
13
-- Fast inference (LPU technology)
14
-- Access to Llama 3.1 70B, Mixtral, Gemma, etc.
15
-
16
-
17
-## Step 2: Configure Backend
18
-
19
-1. **Edit `.env` file:**
20
- ```bash
21
- cd opengrammar/backend
22
- nano .env # or use your favorite editor
23
- ```
24
-
25
-2. **Add your Groq API key:**
26
- ```env
27
- GROQ_API_KEY=gsk_your_actual_api_key_here
28
- ```
29
-
30
-3. **Save the file**
31
-
32
-
33
-## Step 3: Test Groq Integration
34
-
35
-### Option A: Test with Test Script
36
-
37
-```bash
38
-cd opengrammar/backend
39
-node test-groq.js
40
-```
41
-
42
-**Expected Output:**
43
-```
44
-🧪 Testing Groq Grammar Check API...
45
-
46
-Input text: me and him went to the store and buyed some milks
47
-
48
-Sending request to Groq...
49
-
50
-✅ Success! Response:
51
-{
52
- "issues": [
53
- {
54
- "type": "grammar",
55
- "original": "me and him",
56
- "suggestion": "he and I",
57
- "reason": "Subject pronoun error"
58
- },
59
- {
60
- "type": "spelling",
61
- "original": "buyed",
62
- "suggestion": "bought",
63
- "reason": "Irregular verb form"
64
- }
65
- ]
66
-}
67
-
68
-✅ Found 2 issues:
69
-...
70
-```
71
-
72
-### Option B: Start Backend Server
73
-
74
-```bash
75
-npm run dev
76
-```
77
-
78
-Server will start on `http://localhost:8787`
79
-
80
-
81
-## Step 4: Configure Extension
82
-
83
-1. **Click extension icon** in Chrome
84
-
85
-2. **Select Provider:** Groq
86
-
87
-3. **Enter API Key:** (same key from Step 1)
88
-
89
-4. **Select Model:** `llama-3.1-70b-versatile` (recommended)
90
-
91
-5. **Verify Connection:** Green dot should appear
92
-
93
-
94
-## Step 5: Test Grammar Checking
95
-
96
-1. **Open any text box** (Gmail, Google Docs, etc.)
97
-
98
-2. **Type text with errors:**
99
- ```
100
- me and him went to store and buyed milks
101
- ```
102
-
103
-3. **Wait 1 second** - Grammar highlights should appear
104
-
105
-4. **Click highlight** to see suggestions
106
-
107
-5. **Click "Apply"** to fix the error
108
-
109
-
110
-## 🎯 Recommended Groq Models
111
-
112
-| Model | Speed | Quality | Best For |
113
-|-------|-------|---------|----------|
114
-| **llama-3.1-70b-versatile** | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | General grammar checking |
115
-| **llama-3.1-8b-instant** | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | Fast, simple checks |
116
-| **mixtral-8x7b-32768** | ⚡⚡ | ⭐⭐⭐⭐⭐ | Complex writing |
117
-| **gemma2-9b-it** | ⚡⚡⚡ | ⭐⭐⭐⭐ | Balanced performance |
118
-
119
-
120
-## 🔧 Troubleshooting
121
-
122
-### Error: "Invalid API key"
123
-- Check your API key in `.env` file
124
-- Make sure there are no spaces
125
-- Key should start with `gsk_`
126
-
127
-### Error: "Rate limit exceeded"
128
-- Groq free tier: 100 requests/day
129
-- Wait 24 hours or upgrade plan
130
-
131
-### Backend won't start
132
-```bash
133
-# Check if Groq SDK is installed
134
-npm install
135
-
136
-# Check TypeScript
137
-npx tsc --noEmit
138
-
139
-# Restart server
140
-npm run dev
141
-```
142
-
143
-### No grammar highlights
144
-- Verify backend is running: `curl http://localhost:8787/health`
145
-- Check extension settings → Provider should be "Groq"
146
-- Check browser console for errors (F12)
147
-
148
-
149
-## 📊 API Usage
150
-
151
-### Check Usage Dashboard
152
-Visit: https://console.groq.com/usage
153
-
154
-### Monitor in Real-Time
155
-```bash
156
-# Backend logs
157
-npm run dev
158
-
159
-# Watch for API calls
160
-# Look for: "LLM Analysis Error (groq):" in console
161
-```
162
-
163
-
164
-## 💡 Tips
165
-
166
-1. **Use `.env` for testing** - Don't commit API keys to git
167
-2. **Start with llama-3.1-70b** - Best balance of speed/quality
168
-3. **Test with test-groq.js first** - Easier to debug
169
-4. **Monitor usage** - Free tier resets daily
170
-5. **Upgrade when ready** - Paid plans available
171
-
172
-
173
-## 🎉 You're Ready!
174
-
175
-Your OpenGrammar backend is now powered by **Groq's blazing-fast LPU inference**!
176
-
177
-**Next Steps:**
178
-1. Test with real text in browser
179
-2. Try different Groq models
180
-3. Compare with other providers (OpenAI, Ollama)
181
-4. Deploy to production when ready
182
-
183
-
184
-**Need Help?**
185
-- Groq Docs: https://console.groq.com/docs
186
-- OpenGrammar Docs: `TESTING_GUIDE.md`, `SELF_HOSTING.md`
187
0
▼opengrammar/IMPROVEMENTS.md
+0-291
@@ -1,306 +0,0 @@
1
-# Production Improvements Summary
2
-
3
-This document summarizes all improvements made to transform OpenGrammar from MVP to production-ready.
4
-
5
-
6
-## ✅ Completed Improvements
7
-
8
-### 1. Environment Configuration ✓
9
-
10
-**Files Modified/Created:**
11
-- `backend/.dev.vars` - Local development environment variables
12
-- `backend/.dev.vars.example` - Template for developers
13
-- `backend/.env.example` - Production environment template
14
-- `backend/wrangler.toml` - Added production environment config
15
-
16
-**Changes:**
17
-- Separated dev/prod environments in Cloudflare Workers
18
-- Added environment variables for configuration
19
-- Configured debug logging (enabled in dev, disabled in prod)
20
-
21
-
22
-### 2. Interactive Tooltips with Click-to-Apply ✓
23
-
24
-**Files Modified/Created:**
25
-- `extension/src/content/highlighter.ts` - Complete rewrite (555 lines)
26
-
27
-**Features:**
28
-- Beautiful floating tooltips with issue details
29
-- Color-coded by issue type (red=grammar/spelling, amber=clarity, blue=style)
30
-- Three action buttons: Apply, Ignore, Add to Dictionary
31
-- Smooth animations and hover effects
32
-- Click-outside-to-close functionality
33
-- Position-aware rendering (stays within viewport)
34
-
35
-
36
-### 3. Ignore & Dictionary Functionality ✓
37
-
38
-**Files Modified/Created:**
39
-- `extension/src/content/highlighter.ts` - Ignore/dictionary integration
40
-- `extension/src/background/index.ts` - Storage management
41
-- `extension/src/options/options.tsx` - Management UI
42
-
43
-**Features:**
44
-- Ignore issues with persistent storage
45
-- Custom dictionary for false positives
46
-- Manage ignored issues in options page
47
-- Manage dictionary words in options page
48
-- Filter issues before display
49
-
50
-
51
-### 4. Expanded Local Rule Engine ✓
52
-
53
-**Files Modified/Created:**
54
-- `backend/src/analyzer.ts` - Complete rewrite (696 lines)
55
-
56
-**New Rules Added (40+ total):**
57
-- Passive voice detection (enhanced)
58
-- Repetition detection
59
-- Long sentences (>35 words)
60
-- Spacing errors (double spaces, space before punctuation)
61
-- Apostrophe errors (it's/its, your/you're, their/they're)
62
-- That/which usage
63
-- Less/fewer confusion
64
-- Comma splices
65
-- Double negatives
66
-- Redundant phrases (50+ phrases)
67
-- Weak words (100+ replacements)
68
-- Clichés (50+ common clichés)
69
-
70
-
71
-### 5. ContentEditable Highlighting ✓
72
-
73
-**Files Modified/Created:**
74
-- `extension/src/content/index.ts` - Complete rewrite
75
-- `extension/src/content/textExtractor.ts` - Enhanced extraction
76
-- `extension/src/content/utils.ts` - Utility functions
77
-
78
-**Features:**
79
-- MutationObserver for contenteditable elements
80
-- Better text extraction for complex editors
81
-- Caret position tracking
82
-- Scroll handling for highlights
83
-- Support for Gmail, Google Docs, Notion, etc.
84
-- Visibility detection
85
-
86
-
87
-### 6. Error Handling & User Notifications ✓
88
-
89
-**Files Modified/Created:**
90
-- `extension/src/content/index.ts` - Notification system
91
-- `extension/src/background/index.ts` - Error handling
92
-- `backend/src/index.ts` - Error middleware
93
-
94
-**Features:**
95
-- Toast notifications for errors
96
-- Backend health monitoring
97
-- Graceful degradation (AI fails → use rules only)
98
-- User-friendly error messages
99
-- Connection status indicator
100
-
101
-
102
-### 7. Logging & Monitoring ✓
103
-
104
-**Files Modified/Created:**
105
-- `backend/src/index.ts` - Hono logger integration
106
-- `backend/src/index.ts` - Health endpoint
107
-
108
-**Features:**
109
-- Structured logging with Hono logger
110
-- `/health` endpoint for monitoring
111
-- Request/response timing
112
-- Error logging with stack traces
113
-- Periodic health checks (5 min interval)
114
-
115
-
116
-### 8. Comprehensive Options Page ✓
117
-
118
-**Files Modified/Created:**
119
-- `extension/src/options/index.html` - New options page
120
-- `extension/src/options/options.css` - Styling
121
-- `extension/src/options/options.tsx` - Logic
122
-
123
-**Features:**
124
-- General settings (enable/disable, notifications)
125
-- API settings (key, model, backend URL)
126
-- Site-specific settings (disable per domain)
127
-- Custom dictionary management
128
-- Ignored issues management
129
-- Data export/import
130
-- Reset to defaults
131
-- Backend health indicator
132
-- About section with links
133
-
134
-
135
-### 9. Build Verification ✓
136
-
137
-**Files Modified/Created:**
138
-- `extension/vite.config.ts` - Production build config
139
-- `extension/manifest.json` - Updated manifest
140
-- `extension/package.json` - Dependencies
141
-- `backend/package.json` - ES modules
142
-- `backend/src/analyzer.ts` - Type fixes
143
-- `backend/src/index.ts` - Type fixes
144
-
145
-**Build Status:**
146
-- ✅ Extension builds without errors
147
-- ✅ Backend type-checks successfully
148
-- ✅ All TypeScript errors resolved
149
-- ✅ Production assets generated
150
-
151
-
152
-## 📊 Code Metrics
153
-
154
-| Metric | Before | After | Change |
155
-|--------|--------|-------|--------|
156
-| Extension LOC | ~500 | ~2,500 | +400% |
157
-| Backend LOC | ~100 | ~800 | +700% |
158
-| Grammar Rules | 3 | 40+ | +1,233% |
159
-| Files | 15 | 35 | +133% |
160
-| Build Size | ~50KB | ~175KB | +250% |
161
-
162
-
163
-## 🚀 Production Readiness Checklist
164
-
165
-### Code Quality
166
-- [x] TypeScript strict mode
167
-- [x] No type errors
168
-- [x] Proper error handling
169
-- [x] Logging implemented
170
-- [x] Code comments where needed
171
-
172
-### Features
173
-- [x] Interactive tooltips
174
-- [x] Click-to-apply
175
-- [x] Ignore functionality
176
-- [x] Custom dictionary
177
-- [x] Site-specific settings
178
-- [x] 40+ grammar rules
179
-- [x] AI integration
180
-- [x] Real-time checking
181
-
182
-### Infrastructure
183
-- [x] Environment config
184
-- [x] Health monitoring
185
-- [x] Deployment script
186
-- [x] Production documentation
187
-- [x] Build pipeline
188
-
189
-### Security
190
-- [x] API keys stored securely
191
-- [x] No data retention
192
-- [x] CORS configured
193
-- [x] Input validation
194
-- [x] CSP compliance (Manifest V3)
195
-
196
-### UX
197
-- [x] Beautiful UI
198
-- [x] Smooth animations
199
-- [x] Error notifications
200
-- [x] Status indicators
201
-- [x] Responsive design
202
-
203
-
204
-## 📦 Deployment
205
-
206
-### One-Command Deploy
207
-
208
-```bash
209
-./deploy.sh
210
-```
211
-
212
-This script:
213
-1. Checks Node.js version
214
-2. Installs dependencies
215
-3. Deploys backend to Cloudflare Workers
216
-4. Builds extension
217
-5. Provides next steps
218
-
219
-### Manual Deploy
220
-
221
-```bash
222
-# Backend
223
-cd opengrammar/backend
224
-npm install
225
-npx wrangler deploy --env production
226
-
227
-# Extension
228
-cd opengrammar/extension
229
-npm install
230
-npm run build
231
-# Load dist/ in chrome://extensions/
232
-```
233
-
234
-
235
-## 🔗 New Files Created
236
-
237
-### Documentation
238
-- `PRODUCTION.md` - Production deployment guide
239
-- `IMPROVEMENTS.md` - This file
240
-
241
-### Configuration
242
-- `backend/.dev.vars`
243
-- `backend/.dev.vars.example`
244
-- `backend/.env.example`
245
-
246
-### Scripts
247
-- `deploy.sh` - Deployment automation
248
-- `extension/public/create_icons.py` - Icon generation
249
-
250
-### Source Code
251
-- `extension/src/options/index.html`
252
-- `extension/src/options/options.css`
253
-- `extension/src/options/options.tsx`
254
-
255
-### Rewritten Files
256
-- `extension/src/content/highlighter.ts` (555 lines)
257
-- `extension/src/content/index.ts` (282 lines)
258
-- `extension/src/content/textExtractor.ts` (142 lines)
259
-- `extension/src/content/utils.ts` (99 lines)
260
-- `extension/src/background/index.ts` (126 lines)
261
-- `extension/src/popup/popup.tsx` (180 lines)
262
-- `extension/src/popup/popup.css` (220 lines)
263
-- `backend/src/analyzer.ts` (696 lines)
264
-- `backend/src/index.ts` (89 lines)
265
-- `backend/src/shared-types.ts` (42 lines)
266
-- `extension/src/types.ts` (36 lines)
267
-- `shared/src/types.ts` (40 lines)
268
-
269
-
270
-## 🎯 Next Steps (Post-Launch)
271
-
272
-### Phase 2 (Enhanced UX)
273
-- [ ] Tone & style adjustments
274
-- [ ] Writing statistics
275
-- [ ] Custom prompts for AI
276
-- [ ] Better Google Docs support
277
-
278
-### Phase 3 (Advanced Features)
279
-- [ ] Autocomplete
280
-- [ ] Contextual understanding
281
-- [ ] Reading time estimates
282
-- [ ] Vocabulary diversity metrics
283
-
284
-### Phase 4 (Expansion)
285
-- [ ] Firefox support
286
-- [ ] Safari support
287
-- [ ] Desktop apps
288
-- [ ] Developer API
289
-
290
-
291
-**OpenGrammar is now production-ready! 🎉**
292
0
▼opengrammar/PRODUCTION.md
+0-394
@@ -1,409 +0,0 @@
1
-# 🪶 OpenGrammar - Production Documentation
2
-
3
-**Your privacy-first, open-source writing assistant.**
4
-
5
-OpenGrammar is a powerful, self-hostable browser extension that helps you write clearly and confidently everywhere on the web. Built with production-grade architecture for reliability, scalability, and security.
6
-
7
-
8
-## 📦 Production Features
9
-
10
-### ✅ Completed (v1.0.0)
11
-
12
-#### Extension
13
-- **Interactive Tooltips**: Click-to-apply suggestions with beautiful UI
14
-- **Ignore & Dictionary**: Manage ignored issues and custom dictionary words
15
-- **Site-Specific Settings**: Disable on specific domains
16
-- **Smart Notifications**: User-friendly error and status messages
17
-- **Comprehensive Options Page**: Full settings management
18
-- **ContentEditable Support**: Works with Gmail, Google Docs, Notion, etc.
19
-- **Real-time Checking**: Debounced analysis as you type
20
-
21
-#### Backend
22
-- **40+ Grammar Rules**: Passive voice, repetition, spacing, apostrophes, clichés, redundant phrases, weak words, and more
23
-- **AI Integration**: OpenAI/OpenRouter compatible for advanced checking
24
-- **Health Monitoring**: Built-in `/health` endpoint
25
-- **Request Validation**: Input size limits and type checking
26
-- **Error Handling**: Graceful degradation when AI fails
27
-- **Logging**: Structured logging with Hono logger
28
-- **CORS**: Proper cross-origin configuration
29
-
30
-#### Infrastructure
31
-- **Environment Configuration**: Dev/prod separation
32
-- **TypeScript**: Full type safety across codebase
33
-- **Build Pipeline**: Vite + CRX for extension, Wrangler for backend
34
-- **Cloudflare Workers**: Serverless deployment ready
35
-
36
-
37
-## 🚀 Quick Start
38
-
39
-### 1. Deploy Backend (Cloudflare Workers)
40
-
41
-```bash
42
-cd opengrammar/backend
43
-
44
-# Install dependencies
45
-npm install
46
-
47
-# Login to Cloudflare (first time only)
48
-npx wrangler login
49
-
50
-# Deploy to production
51
-npx wrangler deploy --env production
52
-
53
-# Note the deployed URL (e.g., https://opengrammar.yourname.workers.dev)
54
-```
55
-
56
-### 2. Build Extension
57
-
58
-```bash
59
-cd opengrammar/extension
60
-
61
-# Install dependencies
62
-npm install
63
-
64
-# Update backend URL in src/background/index.ts (or set via options page)
65
-# Replace DEFAULT_BACKEND_URL with your deployed URL
66
-
67
-# Build for production
68
-npm run build
69
-
70
-# The built extension will be in dist/
71
-```
72
-
73
-### 3. Load Extension
74
-
75
-1. Open Chrome: `chrome://extensions/`
76
-2. Enable "Developer mode" (top right)
77
-3. Click "Load unpacked"
78
-4. Select `opengrammar/extension/dist` folder
79
-5. Extension icon appears in toolbar
80
-
81
-### 4. Configure
82
-
83
-1. Click extension icon
84
-2. Add your OpenAI/OpenRouter API key (optional, for AI features)
85
-3. Select preferred model
86
-4. Verify backend connection (green status dot)
87
-
88
-
89
-## 🏗️ Architecture
90
-
91
-```
92
-┌─────────────────────────────────────────────────────────────┐
93
-│ Chrome Extension │
94
-│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
95
-│ │ Popup │ │ Options │ │ Content Script │ │
96
-│ │ (React) │ │ Page │ │ (Vanilla TS) │ │
97
-│ └─────────────┘ └──────────────┘ └──────────────────┘ │
98
-│ │ │
99
-│ ┌───────▼────────┐ │
100
-│ │ Background │ │
101
-│ │ Service Worker│ │
102
-│ └───────┬────────┘ │
103
-└────────────────────────────┼────────────────────────────────┘
104
- │ HTTP
105
- ▼
106
-┌─────────────────────────────────────────────────────────────┐
107
-│ Cloudflare Worker (Hono) │
108
-│ ┌──────────────────────────────────────────────────────┐ │
109
-│ │ /analyze → Rule Engine + AI (OpenAI/OpenRouter) │ │
110
-│ │ /health → Status endpoint │ │
111
-│ └──────────────────────────────────────────────────────┘ │
112
-└─────────────────────────────────────────────────────────────┘
113
-```
114
-
115
-
116
-## 📁 Project Structure
117
-
118
-```
119
-opengrammar/
120
-├── backend/
121
-│ ├── src/
122
-│ │ ├── index.ts # Hono API server
123
-│ │ ├── analyzer.ts # Rule-based + LLM analyzers
124
-│ │ └── shared-types.ts # TypeScript interfaces
125
-│ ├── .dev.vars # Local environment variables
126
-│ ├── wrangler.toml # Cloudflare Workers config
127
-│ └── package.json
128
-│
129
-├── extension/
130
-│ ├── src/
131
-│ │ ├── background/ # Service worker
132
-│ │ ├── content/ # Content script (highlights, text extraction)
133
-│ │ ├── popup/ # Popup UI (React)
134
-│ │ ├── options/ # Options page (React)
135
-│ │ └── types.ts # Shared types
136
-│ ├── public/ # Static assets (icons)
137
-│ ├── manifest.json # Extension manifest v3
138
-│ ├── vite.config.ts # Vite build config
139
-│ └── package.json
140
-│
141
-└── shared/
142
- └── src/
143
- └── types.ts # Types shared between backend/extension
144
-```
145
-
146
-
147
-## ⚙️ Configuration
148
-
149
-### Backend Environment Variables
150
-
151
-| Variable | Description | Default |
152
-|----------|-------------|---------|
153
-| `ENV` | Environment name | `development` |
154
-| `DEBUG` | Enable debug logging | `true` (dev), `false` (prod) |
155
-
156
-Set via:
157
-- Local: `.dev.vars` file
158
-- Production: Cloudflare dashboard or `wrangler secret`
159
-
160
-### Extension Settings (chrome.storage.sync)
161
-
162
-| Key | Type | Description |
163
-|-----|------|-------------|
164
-| `enabled` | boolean | Enable/disable extension |
165
-| `apiKey` | string | OpenAI/OpenRouter API key |
166
-| `model` | string | AI model to use |
167
-| `backendUrl` | string | Backend API URL |
168
-| `checkAsYouType` | boolean | Real-time checking |
169
-| `showNotifications` | boolean | Show error notifications |
170
-| `disabledDomains` | string[] | Domains where extension is disabled |
171
-| `dictionary` | string[] | Custom dictionary words |
172
-| `ignoredIssues` | IgnoredIssue[] | Ignored grammar issues |
173
-
174
-
175
-## 🔧 Development
176
-
177
-### Backend Development
178
-
179
-```bash
180
-cd opengrammar/backend
181
-
182
-# Start local development server (http://localhost:8787)
183
-npm run dev
184
-
185
-# Type check
186
-npx wrangler typecheck
187
-
188
-# Deploy to staging
189
-npx wrangler deploy
190
-
191
-# Deploy to production
192
-npx wrangler deploy --env production
193
-```
194
-
195
-### Extension Development
196
-
197
-```bash
198
-cd opengrammar/extension
199
-
200
-# Start dev mode with HMR
201
-npm run dev
202
-
203
-# Build for production
204
-npm run build
205
-
206
-# Type check only
207
-npx tsc --noEmit
208
-```
209
-
210
-### Loading Unpacked Extension (Development)
211
-
212
-1. Build extension: `npm run build`
213
-2. Open `chrome://extensions/`
214
-3. Enable "Developer mode"
215
-4. Click "Load unpacked"
216
-5. Select `dist/` folder
217
-
218
-
219
-## 🛡️ Security
220
-
221
-### API Key Handling
222
-- Keys stored in `chrome.storage.sync` (encrypted by Chrome)
223
-- Never sent to OpenGrammar backend
224
-- Sent directly to OpenAI/OpenRouter from extension
225
-- User controls their own keys
226
-
227
-### Privacy
228
-- No user accounts or databases
229
-- No keystroke logging
230
-- Stateless backend (no data retention)
231
-- All analysis happens client-side or directly with AI provider
232
-
233
-### Content Security
234
-- Manifest V3 CSP compliance
235
-- No remote code execution
236
-- All code bundled locally
237
-
238
-
239
-## 📊 Monitoring & Debugging
240
-
241
-### Backend Logs
242
-
243
-View logs in Cloudflare dashboard:
244
-```bash
245
-# Stream logs in real-time
246
-npx wrangler tail
247
-```
248
-
249
-### Health Check
250
-
251
-```bash
252
-curl https://your-backend.workers.dev/health
253
-```
254
-
255
-Response:
256
-```json
257
-{
258
- "status": "healthy",
259
- "timestamp": "2026-02-28T12:00:00.000Z",
260
- "environment": "production"
261
-}
262
-```
263
-
264
-### Extension Debugging
265
-
266
-1. Right-click extension icon → "Inspect popup"
267
-2. Open `chrome://extensions/` → Click "service worker" → "Inspect"
268
-3. Content script logs: Right-click page → "Inspect" → Console
269
-
270
-
271
-## 🧪 Testing
272
-
273
-### Manual Testing Checklist
274
-
275
-- [ ] Grammar checking in text inputs
276
-- [ ] Grammar checking in textareas
277
-- [ ] Grammar checking in contenteditable (Gmail, Google Docs)
278
-- [ ] Tooltip appears on hover
279
-- [ ] Click-to-apply works
280
-- [ ] Ignore functionality persists
281
-- [ ] Dictionary words not flagged
282
-- [ ] Settings save correctly
283
-- [ ] Backend health indicator accurate
284
-- [ ] Extension works across multiple tabs
285
-- [ ] No console errors
286
-
287
-### Automated Testing (Future)
288
-
289
-```bash
290
-# Backend tests
291
-npm run test
292
-
293
-# Extension tests
294
-npm run test
295
-
296
-# E2E tests (future)
297
-npm run test:e2e
298
-```
299
-
300
-
301
-## 🚨 Troubleshooting
302
-
303
-### Backend Not Connecting
304
-
305
-1. Check backend URL in extension options
306
-2. Verify backend is deployed: `curl https://your-backend/health`
307
-3. Check CORS settings in `backend/src/index.ts`
308
-4. Review Cloudflare Worker logs
309
-
310
-### AI Not Working
311
-
312
-1. Verify API key is valid
313
-2. Check API key has credits/quota
314
-3. Try different model (e.g., `gpt-3.5-turbo`)
315
-4. Check OpenAI/OpenRouter status
316
-
317
-### Highlights Not Appearing
318
-
319
-1. Check extension is enabled (icon badge)
320
-2. Verify site is not in disabled domains
321
-3. Reload the page
322
-4. Check content script loaded (inspect → console)
323
-
324
-### Build Errors
325
-
326
-```bash
327
-# Clear node_modules and rebuild
328
-rm -rf node_modules dist
329
-npm install
330
-npm run build
331
-```
332
-
333
-
334
-## 📈 Performance
335
-
336
-### Benchmarks
337
-
338
-| Metric | Target | Actual |
339
-|--------|--------|--------|
340
-| Extension load time | < 100ms | ~50ms |
341
-| Grammar check (rule-based) | < 50ms | ~20ms |
342
-| Grammar check (AI) | < 3s | ~1-2s |
343
-| Highlight render | < 100ms | ~50ms |
344
-| Memory usage | < 50MB | ~30MB |
345
-
346
-### Optimization Tips
347
-
348
-1. **Debounce**: 800ms delay before checking
349
-2. **Text length limit**: 50,000 characters max
350
-3. **Lazy loading**: Options page loaded on demand
351
-4. **Efficient DOM**: Minimal reflows in highlighter
352
-
353
-
354
-## 🤝 Contributing
355
-
356
-### Code Style
357
-
358
-- TypeScript strict mode
359
-- ESLint + Prettier (configured in root)
360
-- Conventional commits for PRs
361
-
362
-### Pull Request Process
363
-
364
-1. Fork repository
365
-2. Create feature branch
366
-3. Make changes
367
-4. Run type check: `npm run typecheck`
368
-5. Build both projects
369
-6. Submit PR with description
370
-
371
-### Areas for Contribution
372
-
373
-- [ ] More grammar rules
374
-- [ ] Better contenteditable handling
375
-- [ ] Additional languages
376
-- [ ] Accessibility improvements
377
-- [ ] Performance optimizations
378
-- [ ] Documentation
379
-
380
-
381
-## 📄 License
382
-
383
-Apache 2.0 - See [LICENSE](../LICENSE) for details.
384
-
385
-
386
-## 🔗 Links
387
-
388
-- **GitHub**: [github.com/your-repo/opengrammar](https://github.com/your-repo/opengrammar)
389
-- **Issues**: [Report a bug](https://github.com/your-repo/opengrammar/issues)
390
-- **Roadmap**: [See upcoming features](../ROADMAP.md)
391
-- **Cloudflare Workers**: [Documentation](https://developers.cloudflare.com/workers/)
392
-
393
-
394
-**Built with ❤️ by the OpenGrammar community**
395
0
▼opengrammar/SELF_HOSTING.md
+0-349
@@ -1,362 +0,0 @@
1
-# 🐳 OpenGrammar Self-Hosting Guide
2
-
3
-Run OpenGrammar locally with **local LLM support** (Qwen, Phi-4-mini, Llama) using Docker and Ollama.
4
-
5
-
6
-## 🎯 Options Overview
7
-
8
-| Option | Best For | Cost | Privacy |
9
-|--------|----------|------|---------|
10
-| **Cloud APIs** (OpenAI, Groq, Together) | Production, best quality | $0.01-0.10/request | ⭐⭐⭐ |
11
-| **Local Ollama** (Qwen, Phi-4-mini) | Privacy, free, offline | Free (your hardware) | ⭐⭐⭐⭐⭐ |
12
-| **Hybrid** (Rules local + AI cloud) | Balance | Free-$5/mo | ⭐⭐⭐⭐ |
13
-
14
-
15
-## 🚀 Quick Start
16
-
17
-### Option 1: Docker Compose (Recommended)
18
-
19
-```bash
20
-cd opengrammar
21
-
22
-# Start backend only (use cloud APIs)
23
-docker-compose up -d opengrammar-backend
24
-
25
-# Start backend + Ollama with local models (requires GPU for good performance)
26
-docker-compose --profile local-llm up -d
27
-
28
-# Check status
29
-docker-compose ps
30
-
31
-# View logs
32
-docker-compose logs -f
33
-```
34
-
35
-### Option 2: Manual Docker
36
-
37
-```bash
38
-# Build backend image
39
-cd opengrammar/backend
40
-docker build -t opengrammar-backend .
41
-
42
-# Run container
43
-docker run -d \
44
- -p 8787:8787 \
45
- --name opengrammar \
46
- opengrammar-backend
47
-```
48
-
49
-### Option 3: Direct Node.js
50
-
51
-```bash
52
-cd opengrammar/backend
53
-npm install
54
-npm run dev # Runs on http://localhost:8787
55
-```
56
-
57
-
58
-## 🤖 Local LLM Setup with Ollama
59
-
60
-### Step 1: Install Ollama
61
-
62
-**Linux:**
63
-```bash
64
-curl -fsSL https://ollama.com/install.sh | sh
65
-```
66
-
67
-**macOS:**
68
-```bash
69
-brew install ollama
70
-```
71
-
72
-**Windows:**
73
-Download from [ollama.com](https://ollama.com)
74
-
75
-### Step 2: Pull Grammar-Focused Models
76
-
77
-```bash
78
-# Small & fast (good for grammar checking)
79
-ollama pull qwen2.5:0.5b # 0.5B parameters, ~400MB
80
-ollama pull qwen2.5:1.5b # 1.5B parameters, ~1GB
81
-
82
-# Medium quality
83
-ollama pull phi4-mini:3.8b # 3.8B parameters, ~2.5GB
84
-ollama pull llama3.2:3b # 3B parameters, ~2GB
85
-
86
-# High quality (requires GPU)
87
-ollama pull llama3.2:7b # 7B parameters, ~4GB
88
-ollama pull mistral:7b # 7B parameters, ~4GB
89
-```
90
-
91
-### Step 3: Test Ollama
92
-
93
-```bash
94
-# Test the model
95
-ollama run qwen2.5:0.5b "Fix this: me and him went to store"
96
-
97
-# Should respond with corrected grammar
98
-```
99
-
100
-### Step 4: Configure OpenGrammar
101
-
102
-In extension options:
103
-- **Provider:** Ollama (Local)
104
-- **Base URL:** `http://localhost:11434/v1`
105
-- **Model:** `qwen2.5:0.5b` or `qwen2.5:1.5b`
106
-- **API Key:** (leave empty - not needed)
107
-
108
-
109
-## ☁️ Cloud API Setup
110
-
111
-### Supported Providers
112
-
113
-| Provider | Speed | Quality | Cost | Best Models |
114
-|----------|-------|---------|------|-------------|
115
-| **Groq** | ⚡⚡⚡ | ⭐⭐⭐⭐ | Free tier | `llama-3.1-70b-versatile` |
116
-| **Together** | ⚡⚡ | ⭐⭐⭐⭐ | $0.01/1K | `Meta-Llama-3.1-70B` |
117
-| **OpenRouter** | ⚡⚡ | ⭐⭐⭐⭐⭐ | Varies | `claude-3.5-sonnet` |
118
-| **OpenAI** | ⚡ | ⭐⭐⭐⭐⭐ | $0.015/1K | `gpt-4o-mini` |
119
-
120
-### Get API Keys
121
-
122
-1. **Groq:** [console.groq.com](https://console.groq.com) (Free tier: 100 req/day)
123
-2. **Together:** [api.together.ai](https://api.together.ai) ($25 free credit)
124
-3. **OpenRouter:** [openrouter.ai](https://openrouter.ai) (Pay-as-you-go)
125
-4. **OpenAI:** [platform.openai.com](https://platform.openai.com) ($5 free credit)
126
-
127
-### Configure in Extension
128
-
129
-1. Click extension icon → Settings
130
-2. Select provider
131
-3. Enter API key
132
-4. Choose model
133
-5. Test connection
134
-
135
-
136
-## 🔧 Configuration
137
-
138
-### Environment Variables (Backend)
139
-
140
-```bash
141
-# .env file in backend/
142
-PORT=8787
143
-NODE_ENV=production
144
-
145
-# Optional: Default API keys (users can override in extension)
146
-OPENAI_API_KEY=sk-...
147
-GROQ_API_KEY=gsk_...
148
-TOGETHER_API_KEY=...
149
-OPENROUTER_API_KEY=...
150
-
151
-# Ollama URL (for local LLM)
152
-OLLAMA_BASE_URL=http://localhost:11434/v1
153
-```
154
-
155
-### Recommended Models by Use Case
156
-
157
-| Use Case | Model | Provider | RAM Required |
158
-|----------|-------|----------|--------------|
159
-| **Basic grammar** | qwen2.5:0.5b | Ollama | 1GB |
160
-| **Better accuracy** | qwen2.5:1.5b | Ollama | 2GB |
161
-| **Professional writing** | gpt-4o-mini | OpenAI | N/A |
162
-| **Fast + free** | llama-3.1-70b | Groq | N/A |
163
-| **Best quality** | claude-3.5-sonnet | OpenRouter | N/A |
164
-
165
-
166
-## 📊 Performance Benchmarks
167
-
168
-### Local LLM (RTX 4090)
169
-
170
-| Model | Tokens/sec | Grammar Accuracy | RAM |
171
-|-------|------------|------------------|-----|
172
-| qwen2.5:0.5b | ~100 | 75% | 1GB |
173
-| qwen2.5:1.5b | ~80 | 82% | 2GB |
174
-| phi4-mini:3.8b | ~50 | 88% | 4GB |
175
-| llama3.2:7b | ~30 | 90% | 8GB |
176
-
177
-### Cloud APIs
178
-
179
-| Model | Latency | Grammar Accuracy | Cost/1K requests |
180
-|-------|---------|------------------|------------------|
181
-| gpt-4o-mini | ~1s | 95% | $0.15 |
182
-| llama-3.1-70b (Groq) | ~200ms | 92% | Free (tier) |
183
-| claude-3.5-sonnet | ~2s | 96% | $3.00 |
184
-
185
-
186
-## 🔒 Security Considerations
187
-
188
-### Local Deployment
189
-- ✅ All data stays on your machine
190
-- ✅ No API calls
191
-- ✅ Full privacy
192
-- ⚠️ Your hardware cost
193
-
194
-### Cloud APIs
195
-- ✅ Text sent only to chosen provider
196
-- ✅ No logging by OpenGrammar
197
-- ⚠️ API key required
198
-- ⚠️ Data leaves your machine
199
-
200
-### Best Practices
201
-1. Use API keys with spending limits
202
-2. Rotate keys periodically
203
-3. Never commit keys to git
204
-4. Use HTTPS in production
205
-
206
-
207
-## 🛠️ Troubleshooting
208
-
209
-### Backend Won't Start
210
-
211
-```bash
212
-# Check logs
213
-docker-compose logs opengrammar-backend
214
-
215
-# Test health endpoint
216
-curl http://localhost:8787/health
217
-
218
-# Check port conflict
219
-lsof -i :8787
220
-```
221
-
222
-### Ollama Connection Failed
223
-
224
-```bash
225
-# Check Ollama is running
226
-ollama list
227
-
228
-# Test Ollama directly
229
-curl http://localhost:11434/api/tags
230
-
231
-# Restart Ollama
232
-sudo systemctl restart ollama # Linux
233
-brew services restart ollama # macOS
234
-```
235
-
236
-### Docker GPU Support (NVIDIA)
237
-
238
-```bash
239
-# Install NVIDIA Container Toolkit
240
-sudo apt-get install -y nvidia-container-toolkit
241
-
242
-# Configure Docker
243
-sudo nvidia-ctk runtime configure --runtime=docker
244
-sudo systemctl restart docker
245
-
246
-# Run with GPU
247
-docker-compose --profile local-llm up -d
248
-```
249
-
250
-### Models Not Downloading
251
-
252
-```bash
253
-# Check internet connection
254
-ping ollama.com
255
-
256
-# Try alternative mirror
257
-OLLAMA_ORIGINS=https://ollama.ollama.com ollama pull qwen2.5:0.5b
258
-
259
-# Manual download
260
-wget https://ollama.com/download/qwen2.5:0.5b
261
-```
262
-
263
-
264
-## 📈 Scaling
265
-
266
-### Production Deployment
267
-
268
-```bash
269
-# Deploy to cloud (Railway, Render, Fly.io)
270
-railway up # Auto-deploys from GitHub
271
-
272
-# Or use Kubernetes
273
-kubectl apply -f k8s/
274
-
275
-# Load balancer setup
276
-nginx -c nginx.conf
277
-```
278
-
279
-### High Availability
280
-
281
-- Run multiple backend instances
282
-- Use Redis for caching
283
-- Enable request queuing
284
-- Monitor with Prometheus + Grafana
285
-
286
-
287
-## 💡 Tips & Tricks
288
-
289
-### 1. Hybrid Mode (Best of Both Worlds)
290
-
291
-Configure rules to run locally, AI only for complex issues:
292
-
293
-```json
294
-{
295
- "provider": "ollama",
296
- "model": "qwen2.5:0.5b",
297
- "fallbackProvider": "groq",
298
- "fallbackModel": "llama-3.1-70b-versatile"
299
-}
300
-```
301
-
302
-### 2. Custom System Prompt
303
-
304
-Tailor AI behavior for your needs:
305
-
306
-```
307
-You are a grammar expert. Be concise. Only suggest changes that improve clarity.
308
-```
309
-
310
-### 3. Batch Processing
311
-
312
-For long documents, split into chunks:
313
-
314
-```javascript
315
-const chunks = text.split(/\n\n/);
316
-const results = await Promise.all(
317
- chunks.map(chunk => analyze(chunk))
318
-);
319
-```
320
-
321
-### 4. Model Comparison
322
-
323
-Test multiple models on same text:
324
-
325
-```bash
326
-curl http://localhost:8787/analyze \
327
- -d '{"text": "...", "provider": "ollama", "model": "qwen2.5:0.5b"}'
328
-
329
-curl http://localhost:8787/analyze \
330
- -d '{"text": "...", "provider": "groq", "model": "llama-3.1-70b"}'
331
-```
332
-
333
-
334
-## 🎓 Learning Resources
335
-
336
-- [Ollama Documentation](https://ollama.com/docs)
337
-- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
338
-- [Hono Framework](https://hono.dev/docs)
339
-- [OpenAI API Reference](https://platform.openai.com/docs)
340
-
341
-
342
-## 🤝 Support
343
-
344
-- **Issues:** [GitHub Issues](https://github.com/your-repo/opengrammar/issues)
345
-- **Discussions:** [GitHub Discussions](https://github.com/your-repo/opengrammar/discussions)
346
-- **Discord:** [Join our server](https://discord.gg/your-server)
347
-
348
-
349
-**Happy self-hosting! 🎉**
350
0
▼opengrammar/SETUP_GUIDE.md
+0-260
@@ -1,267 +0,0 @@
1
-# 🪶 OpenGrammar - Setup & Usage Guide
2
-
3
-## Quick Start
4
-
5
-### 1. Start the Backend Server
6
-
7
-The backend server provides the grammar checking API. Run it using Node.js:
8
-
9
-```bash
10
-cd opengrammar/backend
11
-npx tsx server-node.ts
12
-```
13
-
14
-The server will start on `http://localhost:8787`
15
-
16
-**Verify it's working:**
17
-```bash
18
-curl http://localhost:8787/health
19
-```
20
-
21
-You should see:
22
-```json
23
-{"status":"healthy","timestamp":"...","environment":"nodejs","version":"2.0.0"}
24
-```
25
-
26
-### 2. Build and Load the Extension
27
-
28
-```bash
29
-cd opengrammar/extension
30
-npm run build
31
-```
32
-
33
-This creates a `dist/` folder with the built extension.
34
-
35
-**Load in Chrome:**
36
-
37
-1. Open Chrome and go to `chrome://extensions/`
38
-2. Enable "Developer mode" (toggle in top right)
39
-3. Click "Load unpacked"
40
-4. Select the `opengrammar/extension/dist` folder
41
-5. The OpenGrammar extension should now appear in your extensions list
42
-
43
-### 3. Configure the Extension
44
-
45
-1. Click the OpenGrammar icon in your browser toolbar
46
-2. Make sure "Enable OpenGrammar" is toggled ON
47
-3. The Backend URL should be set to `http://localhost:8787` (or your deployed URL)
48
-4. The status should show "Connected" with a green dot
49
-
50
-### 4. Test It!
51
-
52
-1. Open the test page: `file:///home/swadhin/fGrammerly/test-grammar.html`
53
-2. Or go to any website with text inputs (Gmail, Google Docs, etc.)
54
-3. Type some text with grammar errors, for example:
55
- - "Teh quick brown fox" (spelling error)
56
- - "Me and him went" (grammar error)
57
- - "We dont care" (missing apostrophe)
58
- - "Their going to love this" (their/they're confusion)
59
-
60
-4. You should see **wavy red underlines** under the errors
61
-5. Click on an underlined word to see the suggestion
62
-6. Click "Apply" to fix the error
63
-
64
-
65
-## Features
66
-
67
-### Grammarly-Style Underlines
68
-
69
-- **Red underline**: Spelling and grammar errors
70
-- **Amber underline**: Clarity issues
71
-- **Blue underline**: Style suggestions
72
-
73
-### Interactive Tooltips
74
-
75
-Click on any underlined text to see:
76
-- The type of error
77
-- Explanation of the issue
78
-- Original text vs. suggestion
79
-- "Apply" button to fix
80
-- "Ignore" button to dismiss
81
-
82
-### Supported Input Types
83
-
84
-- ✅ Text inputs (`<input type="text">`)
85
-- ✅ Textareas (`<textarea>`)
86
-- ✅ Content editable divs (`contenteditable="true"`)
87
-- ✅ Rich text editors (Gmail, Google Docs, Notion, etc.)
88
-
89
-### Grammar Rules
90
-
91
-The extension checks for:
92
-
93
-**Spelling:**
94
-- Common misspellings (teh → the, alot → a lot)
95
-- Missing apostrophes (dont → don't)
96
-
97
-**Grammar:**
98
-- Subject/object pronouns (me and him → he and I)
99
-- Incorrect past tense (runned → ran, writed → wrote)
100
-- Their/there/they're confusion
101
-- Your/you're confusion
102
-- Its/it's confusion
103
-
104
-**Style:**
105
-- Passive voice detection
106
-- Weak words (very good → excellent)
107
-- Redundant phrases (absolutely essential → essential)
108
-
109
-**Clarity:**
110
-- Long sentences (>35 words)
111
-
112
-
113
-## Troubleshooting
114
-
115
-### Extension Not Working?
116
-
117
-1. **Check if backend is running:**
118
- ```bash
119
- curl http://localhost:8787/health
120
- ```
121
-
122
-2. **Check browser console:**
123
- - Press F12 to open DevTools
124
- - Look for OpenGrammar logs
125
- - Common errors:
126
- - "Cannot connect to grammar service" → Backend not running
127
- - "Backend error" → Check backend logs
128
-
129
-3. **Check if extension is enabled:**
130
- - Click the extension icon
131
- - Make sure "Enable OpenGrammar" is ON
132
- - Check the status shows "Connected"
133
-
134
-### Highlights Not Showing?
135
-
136
-1. **For input/textarea:** A red badge appears in the top-right corner showing the number of errors
137
-2. **For contenteditable:** Wavy underlines should appear directly under errors
138
-3. **Try retyping:** The extension checks after you stop typing (800ms delay)
139
-
140
-### False Positives?
141
-
142
-1. Click "Ignore" on the suggestion to dismiss it
143
-2. Add words to your custom dictionary in the Options page
144
-3. Disable the extension for specific domains in Options
145
-
146
-
147
-## Deployment Options
148
-
149
-### Local Development (Current)
150
-```bash
151
-# Terminal 1: Backend
152
-cd opengrammar/backend
153
-npx tsx server-node.ts
154
-
155
-# Terminal 2: Extension (auto-rebuilds)
156
-cd opengrammar/extension
157
-npm run dev
158
-```
159
-
160
-### Production Deployment
161
-
162
-Deploy the backend to a cloud provider:
163
-
164
-**Option 1: Cloudflare Workers**
165
-```bash
166
-cd opengrammar/backend
167
-npx wrangler deploy
168
-```
169
-
170
-**Option 2: Vercel**
171
-```bash
172
-cd opengrammar/backend
173
-npm run deploy:vercel
174
-```
175
-
176
-**Option 3: Docker (with Ollama for local LLM)**
177
-```bash
178
-cd opengrammar
179
-docker-compose up -d
180
-```
181
-
182
-After deploying, update the Backend URL in the extension settings.
183
-
184
-
185
-## API Reference
186
-
187
-### POST /analyze
188
-
189
-Check text for grammar and spelling errors.
190
-
191
-**Request:**
192
-```json
193
-{
194
- "text": "Teh quick brown fox"
195
-}
196
-```
197
-
198
-**Response:**
199
-```json
200
-{
201
- "issues": [
202
- {
203
- "type": "spelling",
204
- "original": "Teh",
205
- "suggestion": "the",
206
- "reason": "Misspelled word...",
207
- "offset": 0,
208
- "length": 3
209
- }
210
- ],
211
- "metadata": {
212
- "textLength": 19,
213
- "issuesCount": 1,
214
- "processingTimeMs": 5
215
- }
216
-}
217
-```
218
-
219
-### GET /health
220
-
221
-Check server health.
222
-
223
-**Response:**
224
-```json
225
-{
226
- "status": "healthy",
227
- "timestamp": "2026-03-01T16:00:00.000Z",
228
- "environment": "nodejs",
229
- "version": "2.0.0"
230
-}
231
-```
232
-
233
-
234
-## What's Fixed
235
-
236
-The recent updates fixed these issues:
237
-
238
-1. ✅ **Grammarly-style wavy underlines** - Now properly shows colored underlines under errors
239
-2. ✅ **Click-to-apply suggestions** - Tooltips work with Apply/Ignore buttons
240
-3. ✅ **Memory leak fixed** - Removed catastrophic regex patterns that caused crashes
241
-4. ✅ **Better content detection** - Improved detection of editable elements
242
-5. ✅ **Proper highlighting** - Text is now properly wrapped with highlight spans
243
-6. ✅ **Node.js backend** - Runs without Cloudflare Workers
244
-
245
-
246
-## Next Steps
247
-
248
-1. **Test on real websites:** Try Gmail, Google Docs, Twitter, etc.
249
-2. **Add API key for AI checking:** Get an OpenAI/Groq key for advanced grammar checking
250
-3. **Customize settings:** Visit Options page to configure per-domain settings
251
-4. **Contribute:** Check ROADMAP.md for planned features
252
-
253
-
254
-## Support
255
-
256
-- **Issues:** Create a GitHub issue
257
-- **Documentation:** See README.md, ROADMAP.md, FEATURES_IMPLEMENTATION.md
258
-- **Logs:** Check `/tmp/opengrammar.log` for backend logs
259
-
260
-Happy writing! ✍️
261
0
▼opengrammar/TESTING_GUIDE.md
+0-354
@@ -1,367 +0,0 @@
1
-# 🧪 OpenGrammar Testing Guide
2
-
3
-## ✅ Build Status
4
-**Extension:** ✅ Builds successfully
5
-**Backend:** ✅ Type-checks successfully
6
-
7
-
8
-## 📋 Step-by-Step Testing Instructions
9
-
10
-### Step 1: Load Extension in Chrome
11
-
12
-1. **Open Chrome Extensions Page**
13
- ```
14
- chrome://extensions/
15
- ```
16
-
17
-2. **Enable Developer Mode**
18
- - Toggle the switch in the top-right corner
19
-
20
-3. **Load Unpacked Extension**
21
- - Click "Load unpacked"
22
- - Navigate to: `opengrammar/extension/dist`
23
- - Click "Select"
24
-
25
-4. **Verify Extension Loaded**
26
- - You should see OpenGrammar icon in toolbar
27
- - Extension version should show v2.0.0+
28
-
29
-
30
-### Step 2: Test Grammar Checking ✍️
31
-
32
-1. **Open any text input** (Gmail, Google Docs, text box, etc.)
33
-
34
-2. **Type text with errors:**
35
- ```
36
- me and him went to the store and buyed some milks. it were very heavy.
37
- ```
38
-
39
-3. **Expected Results:**
40
- - Red underlines appear under errors
41
- - Hover over underlines to see tooltips
42
- - Tooltip shows:
43
- - Issue type (grammar/spelling/style)
44
- - Original text
45
- - Suggestion
46
- - Three buttons: Apply, Ignore, Add to Dictionary
47
-
48
-4. **Test Actions:**
49
- - Click "Apply" → Text should be corrected
50
- - Click "Ignore" → Issue should fade out
51
- - Click "Add to Dictionary" → Word saved for future
52
-
53
-
54
-### Step 3: Test Multi-Provider Support 🔌
55
-
56
-1. **Click Extension Icon** → Open popup
57
-
58
-2. **Test Provider Selection:**
59
- - Select different providers from dropdown:
60
- - OpenAI
61
- - Groq (Free tier available)
62
- - OpenRouter
63
- - Together AI
64
- - Ollama (Local, no API key needed)
65
- - Custom
66
-
67
-3. **For Testing (Recommended):**
68
- - **Option A: Use Groq** (Free, fast)
69
- - Get API key: https://console.groq.com
70
- - Enter key in popup
71
- - Model: `llama-3.1-70b-versatile`
72
-
73
- - **Option B: Use Ollama** (Local, free, private)
74
- ```bash
75
- # Install Ollama first
76
- curl -fsSL https://ollama.com/install.sh | sh
77
- ollama pull qwen2.5:1.5b
78
- ```
79
- - Provider: Ollama
80
- - Model: qwen2.5:1.5b
81
- - API Key: (leave empty)
82
-
83
-4. **Verify Connection:**
84
- - Green dot = Connected ✅
85
- - Red dot = Not connected ❌
86
-
87
-
88
-### Step 4: Test Tone Rewriting ✨
89
-
90
-1. **Select Text on any webpage**
91
-
92
-2. **Right-click → "Rewrite with OpenGrammar"**
93
- - OR press keyboard shortcut: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
94
-
95
-3. **Rewrite Popup Opens:**
96
- - Shows selected text
97
- - 8 tone buttons (Formal 🎩, Casual 😊, Professional 💼, etc.)
98
-
99
-4. **Test Each Tone:**
100
- - Click a tone (e.g., "Formal")
101
- - Click "Rewrite" button
102
- - Wait for AI response
103
- - See rewritten text
104
-
105
-5. **Test Actions:**
106
- - Click "Apply" → Replaces original text
107
- - Click "Copy" → Copies to clipboard
108
-
109
-
110
-### Step 5: Test Writing Statistics 📊
111
-
112
-**Note:** This feature needs a popup entry point. Currently implemented but needs UI integration.
113
-
114
-**To test:**
115
-1. Navigate to `extension/src/stats/index.html` in browser
116
-2. Or create a test page that imports the stats module
117
-
118
-**Metrics to verify:**
119
-- Word count ✅
120
-- Character count ✅
121
-- Flesch Reading Ease Score ✅
122
-- Grade Level ✅
123
-- Reading time estimate ✅
124
-- Vocabulary diversity ✅
125
-
126
-
127
-### Step 6: Test Options Page ⚙️
128
-
129
-1. **Right-click Extension Icon → Options**
130
- - OR click "Open Settings" in popup
131
-
132
-2. **Test Each Section:**
133
-
134
- **General Settings:**
135
- - Toggle "Enable OpenGrammar" on/off
136
- - Toggle "Check as you type"
137
- - Toggle "Show notifications"
138
-
139
- **AI Settings:**
140
- - Enter API key
141
- - Select model from dropdown
142
- - Enter backend URL
143
- - Check backend health status
144
-
145
- **Site-Specific Settings:**
146
- - Add domain: `example.com`
147
- - Verify it appears in list
148
- - Remove domain
149
-
150
- **Custom Dictionary:**
151
- - Add word: `myword`
152
- - Verify it appears in dictionary list
153
- - Remove word
154
-
155
- **Ignored Suggestions:**
156
- - Should show previously ignored issues
157
- - Click "Clear All Ignored Issues"
158
-
159
- **Data Management:**
160
- - Click "Export Settings" → Downloads JSON file
161
- - Click "Import Settings" → Upload JSON file
162
- - Click "Reset All Settings" → Confirms and resets
163
-
164
-
165
-### Step 7: Test Backend API 🔧
166
-
167
-**Start Backend Locally:**
168
-```bash
169
-cd opengrammar/backend
170
-npm install
171
-npm run dev
172
-# Runs on http://localhost:8787
173
-```
174
-
175
-**Test Endpoints:**
176
-
177
-1. **Health Check:**
178
- ```bash
179
- curl http://localhost:8787/health
180
- # Expected: {"status": "healthy", "timestamp": "...", "environment": "development"}
181
- ```
182
-
183
-2. **List Providers:**
184
- ```bash
185
- curl http://localhost:8787/providers
186
- # Expected: List of 6 providers
187
- ```
188
-
189
-3. **Grammar Analysis:**
190
- ```bash
191
- curl -X POST http://localhost:8787/analyze \
192
- -H "Content-Type: application/json" \
193
- -d '{"text": "me and him went"}'
194
- # Expected: List of grammar issues
195
- ```
196
-
197
-4. **Tone Rewriting:**
198
- ```bash
199
- curl -X POST http://localhost:8787/rewrite \
200
- -H "Content-Type: application/json" \
201
- -d '{"text": "hey whats up", "tone": "formal"}'
202
- # Expected: {"rewritten": "Hello, how are you?", ...}
203
- ```
204
-
205
-
206
-### Step 8: Test Docker Deployment 🐳
207
-
208
-**Start with Docker:**
209
-```bash
210
-cd opengrammar
211
-docker-compose up -d
212
-```
213
-
214
-**Verify Services:**
215
-```bash
216
-docker-compose ps
217
-# Should show: opengrammar-backend (healthy)
218
-```
219
-
220
-**Test Backend:**
221
-```bash
222
-curl http://localhost:8787/health
223
-```
224
-
225
-**Stop Services:**
226
-```bash
227
-docker-compose down
228
-```
229
-
230
-**With Ollama (Local LLM):**
231
-```bash
232
-docker-compose --profile local-llm up -d
233
-```
234
-
235
-
236
-## 🐛 Known Issues & Troubleshooting
237
-
238
-### Issue 1: Extension Not Loading
239
-**Solution:**
240
-- Make sure Developer Mode is enabled
241
-- Check `dist/` folder exists and has files
242
-- Try reloading extension
243
-
244
-### Issue 2: No Grammar Highlights
245
-**Solution:**
246
-- Check if extension is enabled (icon badge)
247
-- Verify site is not in disabled domains
248
-- Reload the page
249
-- Check browser console for errors
250
-
251
-### Issue 3: Backend Not Connecting
252
-**Solution:**
253
-```bash
254
-# Check backend is running
255
-curl http://localhost:8787/health
256
-
257
-# Check backend URL in extension options
258
-# Should be: http://localhost:8787
259
-```
260
-
261
-### Issue 4: Rewrite Not Working
262
-**Solution:**
263
-- Make sure text is selected
264
-- Check backend is running
265
-- Verify API key is entered (if using cloud provider)
266
-- Check browser console for errors
267
-
268
-
269
-## ✅ Test Checklist
270
-
271
-Use this checklist to verify all features:
272
-
273
-### Core Features
274
-- [ ] Grammar checking works in text inputs
275
-- [ ] Grammar checking works in textareas
276
-- [ ] Grammar checking works in contenteditable (Gmail, Docs)
277
-- [ ] Tooltips appear on hover
278
-- [ ] Click-to-apply works
279
-- [ ] Ignore functionality works
280
-- [ ] Add to dictionary works
281
-
282
-### Multi-Provider
283
-- [ ] Provider dropdown shows all 6 providers
284
-- [ ] Can switch between providers
285
-- [ ] API key storage works
286
-- [ ] Model selection works
287
-- [ ] Connection status shows correctly
288
-
289
-### Tone Rewriting
290
-- [ ] Context menu appears on text selection
291
-- [ ] Keyboard shortcut works (Ctrl+Shift+R)
292
-- [ ] Rewrite popup opens
293
-- [ ] All 8 tones selectable
294
-- [ ] Rewrite API call works
295
-- [ ] Apply button works
296
-- [ ] Copy button works
297
-
298
-### Options Page
299
-- [ ] General settings save
300
-- [ ] AI settings save
301
-- [ ] Site-specific settings work
302
-- [ ] Dictionary management works
303
-- [ ] Ignored issues management works
304
-- [ ] Export/import works
305
-- [ ] Reset settings works
306
-
307
-### Backend
308
-- [ ] Health endpoint works
309
-- [ ] Providers endpoint works
310
-- [ ] Analyze endpoint works
311
-- [ ] Rewrite endpoint works
312
-- [ ] Docker deployment works
313
-
314
-
315
-## 📊 Test Results Template
316
-
317
-After testing, fill in this template:
318
-
319
-```markdown
320
-## Test Results - [Date]
321
-
322
-**Tester:** [Your Name]
323
-**Browser:** Chrome v[version]
324
-**OS:** [Windows/Mac/Linux]
325
-
326
-### Core Features
327
-- Grammar Checking: ✅/❌
328
-- Tooltips: ✅/❌
329
-- Multi-Provider: ✅/❌
330
-- Tone Rewriting: ✅/❌
331
-- Options Page: ✅/❌
332
-
333
-### Issues Found
334
-1. [Description]
335
-2. [Description]
336
-
337
-### Notes
338
-[Any additional notes]
339
-```
340
-
341
-
342
-## 🎯 Next Steps After Testing
343
-
344
-1. **If all tests pass:** Ready for beta release!
345
-2. **If issues found:** Create GitHub issues with details
346
-3. **Ready to publish:** Prepare Chrome Web Store submission
347
-
348
-
349
-**Happy Testing! 🚀**
350
-
351
-For questions or issues, check the documentation:
352
-- `SELF_HOSTING.md` - Self-hosting guide
353
-- `PRODUCTION.md` - Production deployment
354
-- `FEATURES_IMPLEMENTATION.md` - Feature details
355
0
▼opengrammar/TEST_GRAMMARLY_STYLE.md
+0-224
@@ -1,231 +0,0 @@
1
-# 🧪 Testing Grammarly-Style Highlights
2
-
3
-## ✅ What Was Fixed
4
-
5
-**Before:**
6
-- ❌ Red underlines appeared but no popup
7
-- ❌ No way to see suggestions
8
-- ❌ No "Apply" button
9
-- ❌ Not like Grammarly
10
-
11
-**After:**
12
-- ✅ Red underlines appear
13
-- ✅ Click underline → Popup shows
14
-- ✅ Popup has suggestion + Apply button
15
-- ✅ Click "Apply" → Text is fixed
16
-- ✅ **EXACTLY like Grammarly!**
17
-
18
-
19
-## 🎯 Step-by-Step Test
20
-
21
-### 1. Reload Extension
22
-
23
-```
24
-1. Go to chrome://extensions/
25
-2. Find OpenGrammar
26
-3. Click the reload icon 🔄
27
-4. Wait for "Extension reloaded" message
28
-```
29
-
30
-### 2. Test in Any Text Box
31
-
32
-**Open Gmail, Google Docs, or any text box and type:**
33
-
34
-```
35
-me and him went to the store and buyed some milks
36
-```
37
-
38
-**Expected Behavior:**
39
-
40
-1. **Red underline appears** under "me and him"
41
-2. **Red underline appears** under "buyed"
42
-
43
-### 3. Click the Underline
44
-
45
-**When you click the red underline:**
46
-
47
-✅ **Popup should appear** showing:
48
-```
49
-┌─────────────────────────────┐
50
-│ 🔴 Grammar │
51
-│ │
52
-│ Use subject pronouns (I, │
53
-│ he, she, they, we) when │
54
-│ they are part of the │
55
-│ subject. │
56
-│ │
57
-│ ┌─────────────────────────┐ │
58
-│ │ me and him │ │
59
-│ │ → he and I │ │
60
-│ └─────────────────────────┘ │
61
-│ │
62
-│ ✓ Apply │ ✕ Ignore │
63
-└─────────────────────────────┘
64
-```
65
-
66
-### 4. Click "Apply"
67
-
68
-**When you click "✓ Apply":**
69
-
70
-✅ Text should change from:
71
-```
72
-me and him went to the store
73
-```
74
-
75
-To:
76
-```
77
-he and I went to the store
78
-```
79
-
80
-### 5. Test More Errors
81
-
82
-**Type these and verify underlines + popups:**
83
-
84
-| Error Type | Type This | Should Suggest |
85
-|------------|-----------|----------------|
86
-| **Spelling** | `teh cat` | `the cat` |
87
-| **Irregular Verb** | `I runned fast` | `I ran fast` |
88
-| **Modal + of** | `I could of gone` | `I could have gone` |
89
-| **Contraction** | `I dont know` | `I don't know` |
90
-| **Spelling** | `alot of people` | `a lot of people` |
91
-
92
-
93
-## 🎨 Visual Guide
94
-
95
-### What You Should See:
96
-
97
-```
98
-Step 1: Type text
99
-┌────────────────────────────────────┐
100
-│ me and him went to the store │
101
-│ ~~~~~~~~ │
102
-│ ↑ red underline │
103
-└────────────────────────────────────┘
104
-
105
-Step 2: Click underline
106
-┌────────────────────────────────────┐
107
-│ me and him went to the store │
108
-│ ~~~~~~~~ │
109
-│ │ │
110
-│ ▼ Popup appears │
111
-│ ┌─────────────────────────────┐ │
112
-│ │ 🔴 Grammar │ │
113
-│ │ Use subject pronouns... │ │
114
-│ │ me and him → he and I │ │
115
-│ │ ✓ Apply │ ✕ Ignore │ │
116
-│ └─────────────────────────────┘ │
117
-└────────────────────────────────────┘
118
-
119
-Step 3: Click "Apply"
120
-┌────────────────────────────────────┐
121
-│ he and I went to the store │
122
-│ (text is fixed!) │
123
-└────────────────────────────────────┘
124
-```
125
-
126
-
127
-## 🐛 Troubleshooting
128
-
129
-### Issue: No Red Underlines
130
-
131
-**Solution:**
132
-1. Check backend is running: `curl http://localhost:8787/health`
133
-2. Reload extension in chrome://extensions/
134
-3. Refresh the page (F5)
135
-4. Type at least 5 characters
136
-
137
-### Issue: Underlines But No Popup
138
-
139
-**Solution:**
140
-1. **Click directly on the underline** (not near it)
141
-2. **Wait 500ms** while hovering
142
-3. **Check browser console** (F12) for errors
143
-4. **Reload extension** if needed
144
-
145
-### Issue: Popup Shows But "Apply" Doesn't Work
146
-
147
-**Solution:**
148
-1. Make sure you're in an **editable field**
149
-2. Try in a **simple text box** first (not complex editor)
150
-3. Check **browser console** for errors
151
-4. **Reload the page**
152
-
153
-### Issue: Popup Closes Immediately
154
-
155
-**Solution:**
156
-- This is fixed! Click directly on the underline
157
-- Popup should stay open until you click outside
158
-- If it still closes, reload the extension
159
-
160
-
161
-## ✅ Success Checklist
162
-
163
-Test each feature:
164
-
165
-- [ ] Red underline appears under errors
166
-- [ ] Click underline → Popup appears
167
-- [ ] Popup shows error explanation
168
-- [ ] Popup shows before/after comparison
169
-- [ ] "✓ Apply" button is visible
170
-- [ ] Click "Apply" → Text is corrected
171
-- [ ] "✕ Ignore" button is visible
172
-- [ ] Click "Ignore" → Underline fades
173
-- [ ] Click outside popup → Popup closes
174
-- [ ] Works in Gmail/Google Docs
175
-- [ ] Works in regular text boxes
176
-- [ ] Works in textareas
177
-
178
-
179
-## 🎯 Grammarly Comparison
180
-
181
-| Feature | Grammarly | OpenGrammar |
182
-|---------|-----------|-------------|
183
-| Red underlines | ✅ | ✅ |
184
-| Click to show popup | ✅ | ✅ |
185
-| Shows suggestion | ✅ | ✅ |
186
-| Apply button | ✅ | ✅ |
187
-| Ignore button | ✅ | ✅ |
188
-| Click outside to close | ✅ | ✅ |
189
-| Before/after comparison | ✅ | ✅ |
190
-| Error explanation | ✅ | ✅ |
191
-| Color-coded by type | ✅ | ✅ |
192
-| Smooth animations | ✅ | ✅ |
193
-
194
-**OpenGrammar now works EXACTLY like Grammarly!** 🎉
195
-
196
-
197
-## 🚀 Next Steps
198
-
199
-1. **Test in multiple websites:**
200
- - Gmail
201
- - Google Docs
202
- - Twitter/X
203
- - Facebook
204
- - Reddit
205
-
206
-2. **Test different error types:**
207
- - Spelling (teh → the)
208
- - Grammar (me and him → he and I)
209
- - Verbs (buyed → bought)
210
- - Contractions (dont → don't)
211
-
212
-3. **Test popup interactions:**
213
- - Click to open
214
- - Click Apply
215
- - Click Ignore
216
- - Click outside to close
217
-
218
-4. **Report any issues:**
219
- - Check browser console (F12)
220
- - Note which website
221
- - Note what error type
222
-
223
-
224
-**Happy Testing! The extension should now work exactly like Grammarly!** ✨
225
0
▼opengrammar/TROUBLESHOOTING.md
+0-215
@@ -1,225 +0,0 @@
1
-# 🔧 Quick Troubleshooting Guide
2
-
3
-## Issue: Extension Closes/Crashes
4
-
5
-### ✅ Fixed in Latest Version
6
-
7
-**What was fixed:**
8
-- Better error handling in content script
9
-- Reduced error notifications
10
-- Silent handling of non-critical errors
11
-
12
-**Update and reload:**
13
-```bash
14
-# Rebuild extension
15
-cd opengrammar/extension && npm run build
16
-
17
-# Reload in Chrome:
18
-# chrome://extensions/ → Click reload icon on OpenGrammar
19
-```
20
-
21
-
22
-## Issue: Invalid Model Error
23
-
24
-### ❌ Problem: Using Invalid Groq Model
25
-
26
-**Invalid model:** `openai/gpt-oss-120b` (not a real Groq model)
27
-
28
-### ✅ Solution: Use Valid Groq Models
29
-
30
-**Valid Groq Models:**
31
-- `llama-3.1-70b-versatile` ✅ (Recommended)
32
-- `llama-3.1-8b-instant` ✅ (Fast)
33
-- `gemma2-9b-it` ✅
34
-- `mixtral-8x7b-32768` ✅
35
-
36
-**How to fix:**
37
-1. Click extension icon
38
-2. Select **Groq** provider
39
-3. Choose model: `llama-3.1-70b-versatile`
40
-4. Enter your Groq API key
41
-5. Save settings
42
-
43
-
44
-## Issue: No Grammar Highlights
45
-
46
-### Possible Causes:
47
-
48
-1. **Backend not running**
49
- ```bash
50
- # Start backend
51
- cd opengrammar/backend
52
- npm run dev
53
- ```
54
-
55
-2. **Wrong backend URL**
56
- - Click extension icon
57
- - Backend URL should be: `http://localhost:8787`
58
- - Green dot = Connected ✅
59
-
60
-3. **Extension disabled for site**
61
- - Check options page → Site-specific settings
62
- - Make sure current site is not disabled
63
-
64
-4. **Text too short**
65
- - Extension only checks text with 5+ characters
66
-
67
-
68
-## Issue: API Key Not Working
69
-
70
-### For Groq:
71
-
72
-1. **Get API key from:** https://console.groq.com
73
-2. **Key format:** Should start with `gsk_`
74
-3. **Free tier:** 100 requests/day
75
-4. **Enter in extension:**
76
- - Click icon → API Key field
77
- - Paste key starting with `gsk_`
78
-
79
-### Test API Key:
80
-```bash
81
-cd opengrammar/backend
82
-node test-groq.js
83
-# Should show: ✅ Success!
84
-```
85
-
86
-
87
-## Issue: Model Dropdown Shows Wrong Models
88
-
89
-### ✅ Fixed: Model lists now match providers
90
-
91
-**Groq models:**
92
-- llama-3.1-70b-versatile
93
-- llama-3.1-8b-instant
94
-- gemma2-9b-it
95
-- mixtral-8x7b-32768
96
-
97
-**If models don't update:**
98
-1. Reload extension in chrome://extensions/
99
-2. Clear browser cache
100
-3. Re-open popup
101
-
102
-
103
-## Issue: "2 notes selected" Error
104
-
105
-### Cause:
106
-Text selection handling issue
107
-
108
-### ✅ Fixed:
109
-- Better null checks in background script
110
-- Safer tab messaging
111
-- Error handling for missing tabs
112
-
113
-### Workaround (if issue persists):
114
-1. Reload extension
115
-2. Refresh the page
116
-3. Try selecting text again
117
-
118
-
119
-## Quick Test Checklist
120
-
121
-Test if everything works:
122
-
123
-```bash
124
-# 1. Backend running?
125
-curl http://localhost:8787/health
126
-# Expected: {"status":"healthy",...}
127
-
128
-# 2. Extension loaded?
129
-# Check chrome://extensions/ → OpenGrammar enabled
130
-
131
-# 3. Test grammar check
132
-# Type in text box: "me and him went"
133
-# Expected: Red underline appears
134
-
135
-# 4. Test rewrite
136
-# Select text → Right-click → "Rewrite with OpenGrammar"
137
-# Expected: Rewrite popup opens
138
-```
139
-
140
-
141
-## Debug Mode
142
-
143
-### Enable Debug Logging:
144
-
145
-**Backend:**
146
-```bash
147
-cd opengrammar/backend
148
-DEBUG=true npm run dev
149
-```
150
-
151
-**Extension Console:**
152
-1. Open any page
153
-2. Press F12 → Console
154
-3. Look for OpenGrammar logs
155
-
156
-### Common Log Messages:
157
-
158
-| Message | Meaning |
159
-|---------|---------|
160
-| `Grammar check skipped` | Normal - text too short or not editable |
161
-| `Backend connection issue` | Backend not running or wrong URL |
162
-| `LLM Analysis Error` | API key invalid or rate limit |
163
-| `Settings saved` | ✅ Settings updated successfully |
164
-
165
-
166
-## Reset Everything
167
-
168
-If nothing works, reset:
169
-
170
-```bash
171
-# 1. Clear extension settings
172
-# Extension icon → Settings → Reset All Settings
173
-
174
-# 2. Reload extension
175
-# chrome://extensions/ → Reload OpenGrammar
176
-
177
-# 3. Restart backend
178
-# Ctrl+C → npm run dev
179
-
180
-# 4. Re-test
181
-# Type: "me and him went to store"
182
-# Expected: Grammar highlights appear
183
-```
184
-
185
-
186
-## Still Having Issues?
187
-
188
-### Collect Debug Info:
189
-
190
-1. **Extension version:**
191
- - chrome://extensions/ → Note version number
192
-
193
-2. **Backend logs:**
194
- ```bash
195
- cd opengrammar/backend
196
- npm run dev 2>&1 | tee backend.log
197
- ```
198
-
199
-3. **Browser console:**
200
- - F12 → Console → Copy errors
201
-
202
-4. **Test results:**
203
- ```bash
204
- curl http://localhost:8787/health
205
- curl http://localhost:8787/providers
206
- ```
207
-
208
-### Get Help:
209
-
210
-- Check `TESTING_GUIDE.md` for detailed testing
211
-- Check `GROQ_SETUP.md` for Groq-specific issues
212
-- Check `FEATURES_IMPLEMENTATION.md` for feature details
213
-
214
-
215
-**Last Updated:** After commit `5eb7975` (Error handling improvements)
216
0
▼opengrammar/WHATS_NEW.md
+0-362
@@ -1,375 +0,0 @@
1
-# 🎉 OpenGrammar v2.0 - What's New
2
-
3
-**Multi-Provider AI Support + Local LLM Hosting with Docker**
4
-
5
-
6
-## 🚀 Major Features Added
7
-
8
-### 1. Multi-Provider LLM Support ✅
9
-
10
-Choose from **6 different AI providers**:
11
-
12
-| Provider | Speed | Quality | Cost | Best For |
13
-|----------|-------|---------|------|----------|
14
-| **OpenAI** | ⚡⚡ | ⭐⭐⭐⭐⭐ | $$ | Production, best quality |
15
-| **Groq** | ⚡⚡⚡ | ⭐⭐⭐⭐ | Free tier | Fast + free |
16
-| **OpenRouter** | ⚡⚡ | ⭐⭐⭐⭐⭐ | Varies | Access to 100+ models |
17
-| **Together AI** | ⚡⚡ | ⭐⭐⭐⭐ | $ | Open-source models |
18
-| **Ollama (Local)** | ⚡⚡⚡ | ⭐⭐⭐ | Free | Privacy, offline use |
19
-| **Custom** | - | - | - | Your own API |
20
-
21
-### 2. Local LLM Support with Ollama ✅
22
-
23
-Run grammar checking **100% offline** with local models:
24
-
25
-**Supported Models:**
26
-- `qwen2.5:0.5b` - Ultra fast, 400MB RAM
27
-- `qwen2.5:1.5b` - Balanced, 1GB RAM
28
-- `phi4-mini:3.8b` - Great quality, 2.5GB RAM
29
-- `llama3.2:3b` - Good all-rounder, 2GB RAM
30
-- `mistral:7b` - High quality, 4GB RAM
31
-
32
-**Setup (3 commands):**
33
-```bash
34
-# Install Ollama
35
-curl -fsSL https://ollama.com/install.sh | sh
36
-
37
-# Pull model
38
-ollama pull qwen2.5:1.5b
39
-
40
-# Configure in extension
41
-# Provider: Ollama, Model: qwen2.5:1.5b, API Key: (leave empty)
42
-```
43
-
44
-### 3. Docker Self-Hosting ✅
45
-
46
-Run OpenGrammar locally with **one command**:
47
-
48
-```bash
49
-# Backend only (use cloud APIs)
50
-docker-compose up -d opengrammar-backend
51
-
52
-# Backend + Ollama (local LLM)
53
-docker-compose --profile local-llm up -d
54
-```
55
-
56
-**Includes:**
57
-- Multi-stage Dockerfile for minimal image size
58
-- Health checks for monitoring
59
-- Volume persistence for Ollama models
60
-- GPU support option (NVIDIA)
61
-
62
-### 4. Tone Rewriting API ✅
63
-
64
-New `/rewrite` endpoint for style transformation:
65
-
66
-**Supported Tones:**
67
-- Formal
68
-- Casual
69
-- Professional
70
-- Friendly
71
-- Concise
72
-- Detailed
73
-- Persuasive
74
-- Neutral
75
-
76
-**Example:**
77
-```bash
78
-curl http://localhost:8787/rewrite \
79
- -d '{"text": "hey whats up", "tone": "formal"}'
80
-# Response: {"rewritten": "Hello, how are you?"}
81
-```
82
-
83
-### 5. Enhanced UI ✅
84
-
85
-**Popup Improvements:**
86
-- Provider selection dropdown
87
-- Dynamic model loading
88
-- Custom base URL for self-hosted APIs
89
-- Connection status indicator
90
-- API key toggle (show/hide)
91
-
92
-**Options Page Features:**
93
-- Site-specific disabling
94
-- Custom dictionary management
95
-- Ignored issues list
96
-- Data export/import
97
-- Backend health monitoring
98
-
99
-
100
-## 📁 New Files Created
101
-
102
-### Backend
103
-```
104
-backend/
105
-├── src/
106
-│ ├── analyzer.ts # Multi-provider LLM analyzer
107
-│ ├── index.ts # API with /providers, /models, /rewrite
108
-│ └── shared-types.ts # Provider configs + types
109
-├── Dockerfile # Production Docker image
110
-└── tsconfig.json # Relaxed strict mode
111
-```
112
-
113
-### Extension
114
-```
115
-extension/
116
-├── src/
117
-│ ├── types.ts # Provider + rewrite types
118
-│ ├── background/index.ts # Multi-provider message handling
119
-│ ├── popup/popup.tsx # Provider selection UI
120
-│ └── options/ # Full settings page
121
-└── docker-compose.yml # Docker orchestration
122
-```
123
-
124
-### Documentation
125
-```
126
-├── SELF_HOSTING.md # Complete self-hosting guide
127
-├── IMPROVEMENTS.md # v1.0 improvements
128
-├── PRODUCTION.md # Production deployment
129
-└── WHATS_NEW.md # This file
130
-```
131
-
132
-
133
-## 🎯 Quick Start Guide
134
-
135
-### Option 1: Cloud API (Fastest Setup)
136
-
137
-```bash
138
-# 1. Get API key (Groq free tier)
139
-# Visit: https://console.groq.com
140
-
141
-# 2. Load extension in Chrome
142
-# chrome://extensions/ → Load unpacked → extension/dist
143
-
144
-# 3. Configure
145
-# Click icon → Settings → Provider: Groq → Enter API Key
146
-
147
-# 4. Start writing!
148
-```
149
-
150
-### Option 2: Local Ollama (Privacy First)
151
-
152
-```bash
153
-# 1. Install Ollama
154
-curl -fsSL https://ollama.com/install.sh | sh
155
-
156
-# 2. Pull model
157
-ollama pull qwen2.5:1.5b
158
-
159
-# 3. Start backend
160
-cd backend && npm install && npm run dev
161
-
162
-# 4. Configure extension
163
-# Provider: Ollama, Model: qwen2.5:1.5b
164
-
165
-# 5. Write offline!
166
-```
167
-
168
-### Option 3: Docker (Production Ready)
169
-
170
-```bash
171
-# 1. Start everything
172
-docker-compose --profile local-llm up -d
173
-
174
-# 2. Load extension
175
-# chrome://extensions/ → Load unpacked → extension/dist
176
-
177
-# 3. Configure
178
-# Backend URL: http://localhost:8787
179
-# Provider: Ollama
180
-
181
-# 4. Done!
182
-```
183
-
184
-
185
-## 🔧 Configuration Examples
186
-
187
-### Using Groq (Free, Fast)
188
-
189
-```json
190
-{
191
- "provider": "groq",
192
- "apiKey": "gsk_xxx",
193
- "model": "llama-3.1-70b-versatile",
194
- "backendUrl": "http://localhost:8787"
195
-}
196
-```
197
-
198
-### Using Ollama Local
199
-
200
-```json
201
-{
202
- "provider": "ollama",
203
- "apiKey": "",
204
- "model": "qwen2.5:1.5b",
205
- "backendUrl": "http://localhost:8787"
206
-}
207
-```
208
-
209
-### Using Custom API
210
-
211
-```json
212
-{
213
- "provider": "custom",
214
- "apiKey": "your-key",
215
- "model": "your-model",
216
- "customBaseUrl": "https://your-api.com/v1"
217
-}
218
-```
219
-
220
-
221
-## 📊 Performance Comparison
222
-
223
-| Setup | Latency | Cost | Privacy | Accuracy |
224
-|-------|---------|------|---------|----------|
225
-| **Groq (Llama-70B)** | 200ms | Free | ⭐⭐⭐ | 92% |
226
-| **OpenAI (GPT-4o-mini)** | 1s | $0.01/10 | ⭐⭐⭐ | 95% |
227
-| **Ollama (Qwen-1.5B)** | 500ms | Free | ⭐⭐⭐⭐⭐ | 82% |
228
-| **Ollama (Phi-4-mini)** | 800ms | Free | ⭐⭐⭐⭐⭐ | 88% |
229
-| **Rules Only** | 20ms | Free | ⭐⭐⭐⭐⭐ | 60% |
230
-
231
-
232
-## 🛡️ Security & Privacy
233
-
234
-### What Changed
235
-
236
-| Aspect | Before | After |
237
-|--------|--------|-------|
238
-| **Data Flow** | Extension → Your Backend → OpenAI | Extension → Your Backend → Provider of Choice |
239
-| **API Keys** | Stored in chrome.storage | Same + supports multiple providers |
240
-| **Local Option** | Rules only | Full LLM with Ollama |
241
-| **Self-Hosting** | Cloudflare Workers only | Docker + any cloud |
242
-
243
-### Privacy Modes
244
-
245
-1. **Maximum Privacy**: Ollama local + rules only
246
-2. **Balanced**: Rules local + cloud AI for complex issues
247
-3. **Best Quality**: Cloud AI for everything
248
-
249
-
250
-## 🧪 Testing
251
-
252
-### Test Providers
253
-
254
-```bash
255
-# Health check
256
-curl http://localhost:8787/health
257
-
258
-# List providers
259
-curl http://localhost:8787/providers
260
-
261
-# Get models for provider
262
-curl http://localhost:8787/models \
263
- -d '{"provider": "ollama"}'
264
-
265
-# Test grammar check
266
-curl http://localhost:8787/analyze \
267
- -d '{"text": "me and him went", "provider": "ollama"}'
268
-
269
-# Test rewrite
270
-curl http://localhost:8787/rewrite \
271
- -d '{"text": "hey", "tone": "formal"}'
272
-```
273
-
274
-### Test Extension
275
-
276
-1. Load unpacked extension
277
-2. Open popup → Select provider
278
-3. Enter API key (if required)
279
-4. Type in any text box
280
-5. Verify highlights appear
281
-6. Click highlight → Apply suggestion
282
-
283
-
284
-## 🚀 Next Steps (Future)
285
-
286
-### Phase 2 (Enhanced UX)
287
-- [ ] Streaming responses for faster UX
288
-- [ ] Writing statistics dashboard
289
-- [ ] Browser sync for settings
290
-- [ ] Keyboard shortcuts
291
-
292
-### Phase 3 (Advanced Features)
293
-- [ ] Multi-language support
294
-- [ ] Custom rule builder UI
295
-- [ ] Team/shared dictionaries
296
-- [ ] Analytics dashboard
297
-
298
-### Phase 4 (Platform Expansion)
299
-- [ ] Firefox extension
300
-- [ ] Safari extension
301
-- [ ] VS Code extension
302
-- [ ] Desktop app
303
-
304
-
305
-## 🤝 Migration Guide
306
-
307
-### From v1.0 to v2.0
308
-
309
-**No breaking changes!** Your existing settings will work:
310
-
311
-1. Old `apiKey` field still works (defaults to OpenAI)
312
-2. Old `model` field still works
313
-3. Old `backendUrl` field still works
314
-
315
-**To use new features:**
316
-
317
-1. Update backend: `npm install` (new dependencies)
318
-2. Rebuild extension: `npm run build`
319
-3. Reload extension in Chrome
320
-4. Select new provider in popup
321
-
322
-### From Other Grammar Tools
323
-
324
-**Moving from Grammarly/ProWritingAid:**
325
-
326
-1. Export your dictionary (if possible)
327
-2. Import in OpenGrammar options
328
-3. Configure preferred AI provider
329
-4. Install extension
330
-5. Disable old extension
331
-
332
-
333
-## 📖 Documentation
334
-
335
-| Document | Purpose |
336
-|----------|---------|
337
-| **[SELF_HOSTING.md](SELF_HOSTING.md)** | Complete self-hosting guide |
338
-| **[PRODUCTION.md](PRODUCTION.md)** | Production deployment |
339
-| **[IMPROVEMENTS.md](IMPROVEMENTS.md)** | v1.0 improvements |
340
-| **[ROADMAP.md](ROADMAP.md)** | Future development |
341
-| **[README.md](README.md)** | Getting started |
342
-
343
-
344
-## 🙏 Credits
345
-
346
-**Built with:**
347
-- [Hono](https://hono.dev/) - Web framework
348
-- [OpenAI SDK](https://openai.com/) - Multi-provider support
349
-- [Ollama](https://ollama.com/) - Local LLM
350
-- [React](https://react.dev/) - UI
351
-- [Vite](https://vitejs.dev/) - Build tool
352
-- [Docker](https://docker.com/) - Containerization
353
-
354
-
355
-## 📄 License
356
-
357
-Apache 2.0 - Same as before
358
-
359
-
360
-**Happy writing with OpenGrammar v2.0! ✨**
361
-
362
-*Now with more choices, better privacy, and full self-hosting support.*
363
0
▼opengrammar/backend/.gitignore
+1-0
@@ -1 +1,2 @@
1
1
.vercel
2
+.env*.local
2
3
▼opengrammar/backend/MULTI_PLATFORM.md
+0-145
@@ -1,145 +0,0 @@
1
-# 🚀 OpenGrammar Backend — Multi-Platform Deployment
2
-
3
-The backend is a [Hono](https://hono.dev) application with a **single shared codebase** that runs on multiple platforms via thin adapters.
4
-
5
-## Architecture
6
-
7
-```
8
-backend/src/index.ts ← Shared Hono app (all routes & logic)
9
- │
10
- ├── wrangler.toml → Cloudflare Workers (edge, V8 isolates)
11
- ├── api/index.ts → Vercel (Node.js serverless)
12
- ├── netlify/functions/ → Netlify (Node.js serverless)
13
- ├── server-deno.ts → Deno Deploy (edge, Deno runtime)
14
- ├── server-node.ts → Render / Railway (long-running Node.js)
15
- └── Dockerfile → Docker Hub / self-host
16
-```
17
-
18
-## 🌍 Live Deployments
19
-
20
-| Platform | URL | Status |
21
-|---|---|---|
22
-| ☁️ Cloudflare Workers | `https://opengrammar-backend-production.thelabrats-dev.workers.dev` | ✅ Primary |
23
-| △ Vercel | `https://opengrammar-backend-psi.vercel.app` | ✅ Live |
24
-| 🟩 Netlify | `https://clinquant-sherbet-151cc5.netlify.app` | ✅ Live |
25
-| 🦕 Deno Deploy | `https://opengrammar-backend.deno.dev` | ⏳ Pending setup |
26
-| 🐳 Docker Hub | `docker pull swadhinbiswas/opengrammar-backend` | ⏳ Pending setup |
27
-
28
-## 🤖 Automated CI/CD
29
-
30
-Every push to `main` that changes `backend/**` automatically deploys to **all platforms** via GitHub Actions.
31
-
32
-**Workflow file:** `.github/workflows/deploy-backend.yml`
33
-
34
-You can also trigger a manual deployment to a specific platform:
35
-1. Go to **Actions** tab on GitHub
36
-2. Select **"Deploy Backend — All Platforms"**
37
-3. Click **"Run workflow"** → choose a specific platform
38
-
39
-## 🔑 Required GitHub Secrets
40
-
41
-Go to **Settings → Secrets and variables → Actions** and add:
42
-
43
-| Secret | How to get it |
44
-|---|---|
45
-| `CLOUDFLARE_API_TOKEN` | [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens) → Create Token → "Edit Cloudflare Workers" |
46
-| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Dashboard → Right sidebar on any domain |
47
-| `VERCEL_TOKEN` | [vercel.com/account/tokens](https://vercel.com/account/tokens) |
48
-| `VERCEL_ORG_ID` | `cat backend/.vercel/project.json` → `orgId` |
49
-| `VERCEL_PROJECT_ID` | `cat backend/.vercel/project.json` → `projectId` |
50
-| `NETLIFY_AUTH_TOKEN` | [app.netlify.com/user/applications](https://app.netlify.com/user/applications) → Personal access tokens |
51
-| `NETLIFY_SITE_ID` | Netlify Dashboard → Site → Settings → General → Site ID |
52
-| `DENO_DEPLOY_TOKEN` | [dash.deno.com/account#access-tokens](https://dash.deno.com/account#access-tokens) |
53
-| `DOCKERHUB_USERNAME` | Your Docker Hub username (`swadhinbiswas`) |
54
-| `DOCKERHUB_TOKEN` | [hub.docker.com/settings/security](https://hub.docker.com/settings/security) → New Access Token |
55
-
56
-## 🐳 Docker Hub
57
-
58
-### Pull and run (anyone can do this)
59
-```bash
60
-docker run -p 8787:8787 swadhinbiswas/opengrammar-backend:latest
61
-```
62
-
63
-### With environment variables
64
-```bash
65
-docker run -p 8787:8787 \
66
- -e GROQ_API_KEY=your_key \
67
- -e OPENAI_API_KEY=your_key \
68
- swadhinbiswas/opengrammar-backend:latest
69
-```
70
-
71
-### Build locally
72
-```bash
73
-cd backend
74
-docker build -t opengrammar-backend .
75
-docker run -p 8787:8787 opengrammar-backend
76
-```
77
-
78
-## 🌐 Platform Details
79
-
80
-### Cloudflare Workers (Primary)
81
-- **Runtime:** V8 isolates (no Node.js)
82
-- **Cold start:** ~0ms (always warm)
83
-- **Free tier:** 100,000 req/day
84
-- **Global:** 300+ PoPs — runs at the CDN edge
85
-
86
-### Vercel
87
-- **Runtime:** Node.js 20 serverless functions
88
-- **Cold start:** ~200-500ms
89
-- **Free tier:** 100GB-hours/month
90
-
91
-### Netlify
92
-- **Runtime:** Node.js serverless functions (AWS Lambda)
93
-- **Cold start:** ~300-700ms
94
-- **Free tier:** 125,000 function calls/month
95
-
96
-### Deno Deploy
97
-- **Runtime:** Deno (Web Standard APIs, same as CF Workers)
98
-- **Cold start:** ~0ms (always warm)
99
-- **Free tier:** 100,000 req/day
100
-
101
-### Docker / Self-hosted
102
-- **Runtime:** Node.js 20 + tsx
103
-- **Port:** 8787
104
-- **OS:** linux/amd64 and linux/arm64 (multi-arch)
105
-
106
-## 📡 Can I use it as a CDN?
107
-
108
-The API is **dynamic** — it processes different text on every request, so you can't cache it like static files. However:
109
-
110
-- **Cloudflare Workers** runs inside Cloudflare's global CDN network at 300+ edge locations
111
-- Users in Asia get served from Singapore, US users from New York — **CDN-level latency**
112
-- Static endpoints like `/health` and `/providers` can have `Cache-Control` headers added to truly cache at the edge
113
-
114
-## 🔌 API Reference
115
-
116
-| Method | Endpoint | Description |
117
-|---|---|---|
118
-| `GET` | `/` | Status dashboard |
119
-| `GET` | `/health` | Health check |
120
-| `GET` | `/providers` | List AI providers |
121
-| `POST` | `/analyze` | Grammar analysis |
122
-| `POST` | `/autocomplete` | Text completion |
123
-| `POST` | `/rewrite` | Tone rewriting |
124
-
125
-### Example
126
-```bash
127
-curl -X POST https://opengrammar-backend-psi.vercel.app/analyze \
128
- -H "Content-Type: application/json" \
129
- -d '{"text": "Me and him went to store yesterday"}'
130
-```
131
-
132
-## 🛠️ Local Development
133
-
134
-```bash
135
-cd backend
136
-
137
-# Bun (fastest)
138
-bun run dev
139
-
140
-# Node.js
141
-npm run dev:node
142
-
143
-# Cloudflare Workers local emulation
144
-bun run wrangler dev
145
-```
146
0
▼opengrammar/backend/RAILWAY_DEPLOYMENT.md
+0-104
@@ -1,104 +0,0 @@
1
-# Railway Deployment Guide
2
-
3
-## Quick Deploy
4
-
5
-[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/opengrammar-backend)
6
-
7
-## Setup Instructions
8
-
9
-### 1. Install Railway CLI
10
-```bash
11
-npm install -g @railway/cli
12
-```
13
-
14
-### 2. Login
15
-```bash
16
-railway login
17
-```
18
-
19
-### 3. Initialize Project
20
-```bash
21
-cd opengrammar/backend
22
-railway init
23
-```
24
-
25
-### 4. Deploy
26
-```bash
27
-railway up
28
-```
29
-
30
-### 5. Set Environment Variables
31
-```bash
32
-railway variables set \
33
- NODE_ENV=production \
34
- GROQ_API_KEY=your_key \
35
- OPENAI_API_KEY=your_key
36
-```
37
-
38
-### 6. Get Your URL
39
-```bash
40
-railway domain
41
-# Returns: https://your-app.railway.app
42
-```
43
-
44
-### 7. Update Extension
45
-Backend URL: `https://your-app.railway.app`
46
-
47
-## Pricing
48
-
49
-- **Trial**: $5 credit (no card required)
50
-- **Hobby**: $5/month
51
- - Always-on
52
- - 5GB RAM
53
- - 100GB bandwidth
54
- - Good for production
55
-
56
-## Advantages Over Render
57
-
58
-✅ No sleep on free tier
59
-✅ Faster wake-up time
60
-✅ Better performance
61
-✅ More generous free tier
62
-✅ Easy scaling
63
-
64
-## Testing
65
-
66
-```bash
67
-curl https://your-app.railway.app/health
68
-curl -X POST https://your-app.railway.app/analyze \
69
- -H "Content-Type: application/json" \
70
- -d '{"text": "test"}'
71
-```
72
-
73
-## Auto-Deploy
74
-
75
-Railway auto-deploys on git push:
76
-```bash
77
-git push origin main
78
-# Railway automatically rebuilds and deploys
79
-```
80
-
81
-## Logs
82
-
83
-```bash
84
-# View logs in real-time
85
-railway logs
86
-```
87
-
88
-## Database (Optional)
89
-
90
-If you add database later:
91
-```bash
92
-# Add PostgreSQL
93
-railway add postgresql
94
-
95
-# Connect to your service
96
-railway link
97
-```
98
-
99
-## Scaling
100
-
101
-Railway auto-scales vertically:
102
-- More RAM
103
-- More CPU
104
-- Pay for what you use
105
0
▼opengrammar/backend/README.npm.md
+0-95
@@ -1,95 +0,0 @@
1
-# opengrammar-server
2
-
3
-> Privacy-first, open-source grammar intelligence server — run it on **any device**.
4
-
5
-[![npm version](https://img.shields.io/npm/v/opengrammar-server)](https://www.npmjs.com/package/opengrammar-server)
6
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
-
8
-Turn **any device** into a local OpenGrammar API server — your old Android phone via Termux, a Raspberry Pi, an old laptop, or any VPS.
9
-
10
-## Quick Start
11
-
12
-```bash
13
-# Run instantly (no install needed)
14
-npx opengrammar-server
15
-
16
-# Or install globally
17
-npm install -g opengrammar-server
18
-opengrammar-server
19
-```
20
-
21
-That's it. Your server is live at `http://localhost:8787` 🎉
22
-
23
-## Options
24
-
25
-```bash
26
-opengrammar-server --port 3000 # Custom port
27
-opengrammar-server --host 127.0.0.1 # Localhost only (more secure)
28
-opengrammar-server --help # Show all options
29
-opengrammar-server --version # Show version
30
-```
31
-
32
-## API Endpoints
33
-
34
-| Method | Endpoint | Description |
35
-|--------|----------|-------------|
36
-| `GET` | `/` | Status dashboard |
37
-| `GET` | `/health` | Health check |
38
-| `POST` | `/analyze` | Grammar analysis |
39
-| `POST` | `/autocomplete`| Text completion |
40
-| `GET` | `/providers` | List AI providers |
41
-
42
-### Example
43
-
44
-```bash
45
-# Check health
46
-curl http://localhost:8787/health
47
-
48
-# Analyze text
49
-curl -X POST http://localhost:8787/analyze \
50
- -H "Content-Type: application/json" \
51
- -d '{"text": "Me and him went to store yesterday"}'
52
-```
53
-
54
-## 🤖 Run on Android (Termux)
55
-
56
-Turn your old Android phone into a grammar server!
57
-
58
-```bash
59
-# 1. Install Termux from F-Droid (not Play Store)
60
-# 2. Inside Termux:
61
-pkg update && pkg install nodejs
62
-npx opengrammar-server --port 8787
63
-```
64
-
65
-Your phone is now a grammar server accessible on your local network at `http://<phone-ip>:8787`.
66
-
67
-## 🍓 Run on Raspberry Pi
68
-
69
-```bash
70
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
71
-sudo apt-get install -y nodejs
72
-npx opengrammar-server
73
-```
74
-
75
-## 🐳 Docker
76
-
77
-```bash
78
-docker run -p 8787:8787 swadhinbiswas/opengrammar-backend:latest
79
-```
80
-
81
-## Environment Variables
82
-
83
-| Variable | Description |
84
-|----------|-------------|
85
-| `PORT` | Server port (default: `8787`) |
86
-| `HOST` | Bind host (default: `0.0.0.0`) |
87
-| `GROQ_API_KEY` | Groq API key for AI features (optional) |
88
-| `OPENAI_API_KEY` | OpenAI API key (optional) |
89
-
90
-## Links
91
-
92
-- 🌐 **Website:** https://opengrammer.eu.cc
93
-- 📦 **GitHub:** https://github.com/swadhinbiswas/opengrammar
94
-- 🐛 **Issues:** https://github.com/swadhinbiswas/opengrammar/issues
95
-- ☁️ **Hosted API:** https://opengrammar-backend-production.thelabrats-dev.workers.dev
96
0
▼opengrammar/backend/RENDER_DEPLOYMENT.md
+0-100
@@ -1,100 +0,0 @@
1
-# Render Deployment Guide
2
-
3
-## Quick Deploy
4
-
5
-[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/your-username/opengrammar)
6
-
7
-## Setup Instructions
8
-
9
-### 1. Create New Web Service on Render
10
-
11
-1. Go to [Render Dashboard](https://dashboard.render.com/)
12
-2. Click "New +" → "Web Service"
13
-3. Connect your GitHub repository
14
-4. Configure:
15
- - **Name**: opengrammar-backend
16
- - **Region**: Choose closest to your users
17
- - **Branch**: main
18
- - **Root Directory**: `opengrammar/backend`
19
- - **Runtime**: Node
20
- - **Build Command**: `npm install`
21
- - **Start Command**: `npx tsx src/index.ts`
22
-
23
-### 2. Environment Variables
24
-
25
-In Render dashboard, add these environment variables:
26
-
27
-```
28
-NODE_ENV=production
29
-GROQ_API_KEY=your_groq_key
30
-OPENAI_API_KEY=your_openai_key (optional)
31
-OPENROUTER_API_KEY=your_openrouter_key (optional)
32
-DEBUG=false
33
-```
34
-
35
-### 3. Deploy
36
-
37
-Click "Create Web Service"
38
-
39
-Render will:
40
-- Install dependencies
41
-- Build your app
42
-- Deploy to https://opengrammar-backend.onrender.com
43
-
44
-### 4. Update Extension
45
-
46
-In your extension settings:
47
-- Backend URL: `https://opengrammar-backend.onrender.com`
48
-
49
-## Pricing
50
-
51
-- **Free Tier**:
52
- - 750 hours/month (always-on)
53
- - 0.5GB RAM
54
- - Good for testing/small usage
55
-
56
-- **Starter**: $7/month
57
- - Always-on
58
- - More resources
59
-
60
-## Testing
61
-
62
-```bash
63
-# Test health
64
-curl https://opengrammar-backend.onrender.com/health
65
-
66
-# Test analysis
67
-curl -X POST https://opengrammar-backend.onrender.com/analyze \
68
- -H "Content-Type: application/json" \
69
- -d '{"text": "me and him went"}'
70
-```
71
-
72
-## Auto-Sleep (Free Tier)
73
-
74
-Free tier services sleep after 15 minutes of inactivity.
75
-First request after sleep takes ~30 seconds to wake up.
76
-
77
-**Solutions:**
78
-1. Upgrade to Starter ($7/month) for always-on
79
-2. Use UptimeRobot (free) to ping every 14 minutes
80
-3. Use Railway instead (see RAILWAY_DEPLOYMENT.md)
81
-
82
-## Logs
83
-
84
-View logs in Render dashboard:
85
-- Real-time logs
86
-- Error tracking
87
-- Request logs
88
-
89
-## Custom Domain (Optional)
90
-
91
-1. Go to Settings → Custom Domain
92
-2. Add your domain
93
-3. Configure DNS
94
-4. HTTPS auto-configured
95
-
96
-## Scaling
97
-
98
-Render auto-scales based on traffic.
99
-Free tier: Single instance
100
-Paid tiers: Auto-scaling available
101
0
▼opengrammar/backend/VERCEL_DEPLOYMENT.md
+0-83
@@ -1,83 +0,0 @@
1
-# Vercel deployment for OpenGrammar Backend
2
-
3
-## Quick Deploy
4
-
5
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/your-username/opengrammar/tree/main/opengrammar/backend)
6
-
7
-## Setup Instructions
8
-
9
-### 1. Install Vercel CLI
10
-```bash
11
-npm install -g vercel
12
-```
13
-
14
-### 2. Login to Vercel
15
-```bash
16
-vercel login
17
-```
18
-
19
-### 3. Deploy
20
-```bash
21
-cd opengrammar/backend
22
-vercel --prod
23
-```
24
-
25
-### 4. Set Environment Variables
26
-```bash
27
-# In Vercel dashboard or via CLI:
28
-vercel env add GROQ_API_KEY
29
-vercel env add OPENAI_API_KEY
30
-vercel env add OPENROUTER_API_KEY
31
-```
32
-
33
-### 5. Update Extension
34
-After deployment, Vercel will give you a URL like:
35
-`https://opengrammar-backend.vercel.app`
36
-
37
-Update your extension settings:
38
-- Backend URL: `https://opengrammar-backend.vercel.app`
39
-
40
-## Features
41
-
42
-✅ Serverless deployment
43
-✅ Free tier (100GB-hours/month)
44
-✅ Auto-scaling
45
-✅ HTTPS by default
46
-✅ Global CDN
47
-✅ Zero configuration
48
-
49
-## Environment Variables
50
-
51
-Set these in Vercel dashboard (Project Settings → Environment Variables):
52
-
53
-| Variable | Required | Description |
54
-|----------|----------|-------------|
55
-| `GROQ_API_KEY` | Optional | Groq API key for AI |
56
-| `OPENAI_API_KEY` | Optional | OpenAI API key |
57
-| `OPENROUTER_API_KEY` | Optional | OpenRouter API key |
58
-| `DEBUG` | Optional | Enable debug logging |
59
-
60
-## Testing
61
-
62
-After deployment:
63
-```bash
64
-# Test health endpoint
65
-curl https://your-app.vercel.app/health
66
-
67
-# Test analysis
68
-curl -X POST https://your-app.vercel.app/analyze \
69
- -H "Content-Type: application/json" \
70
- -d '{"text": "me and him went"}'
71
-```
72
-
73
-## Pricing
74
-
75
-- **Free Tier**: 100GB-hours/month, enough for ~10K requests/day
76
-- **Pro**: $20/month for more usage
77
-
78
-## Notes
79
-
80
-- Vercel uses Node.js runtime (not Cloudflare Workers)
81
-- All features work the same
82
-- No wrangler.toml needed on Vercel
83
-- CORS is already enabled
84
0