swadhin / opengrammar public

docs: add project README with detailed overview

swadhinbiswas committed 8 months ago
356d58b
1 parent 7bdc296
commit 356d58b
1 file changed
+96 -0
Showing 1 changed file+96-0
README.md
▼README.md
+96-0
@@ -0,0 +1,96 @@
1
+# 🪶 OpenGrammar
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. It's built to feel like the premium writing assistants you know, but with a critical difference: **you control your data, and it can run completely for free.**
6
+
7
+---
8
+
9
+## 🌟 Why OpenGrammar?
10
+
11
+Most popular grammar assistants require you to send every keystroke to their servers and charge a hefty monthly fee for advanced features. OpenGrammar changes that:
12
+
13
+1. **Zero Cost Option:** The core engine runs locally in your browser, checking for passive voice, repetition, and readability without needing a server or an internet connection.
14
+2. **Bring Your Own AI:** Want advanced, context-aware grammar corrections? Just paste in your own API key (like OpenAI, Groq, or OpenRouter). You pay only fractions of a cent for what you actually use, directly to the AI provider.
15
+3. **Absolute Privacy:** We don't have a database. We don't have user accounts. Your API key never leaves your browser. If you use the AI features, your text is sent securely to a stateless edge function, processed, and immediately forgotten.
16
+4. **Open Source & Self-Hosted:** You can deploy the backend to Cloudflare Workers or Vercel Edge for free in one command. You own the infrastructure.
17
+
18
+## ✨ Features
19
+
20
+- **Works Everywhere:** Seamlessly integrates into text inputs, textareas, and rich text editors (like Gmail, Google Docs, Notion, and Reddit).
21
+- **Blazing Fast:** Built with modern web technologies (React, Vite, Manifest V3) for minimal performance impact.
22
+- **Dual-Engine Architecture:**
23
+ - *Rule-Based (Free & Offline):* Catches passive voice, repeated words, and overly long sentences.
24
+ - *AI-Powered (Requires API Key):* Advanced grammar, spelling, clarity, and stylistic suggestions using models like GPT-4 or open-source alternatives via OpenRouter.
25
+- **Intuitive UI:** Familiar red, yellow, and blue underlines with click-to-apply suggestions.
26
+- **Customizable:** Toggle the extension on or off per website, choose your preferred AI model, and manage your privacy settings.
27
+
28
+---
29
+
30
+## 🚀 Getting Started (For Users)
31
+
32
+*Note: Since this is an open-source developer project, it is not yet published on the Chrome Web Store. You will need to load it manually.*
33
+
34
+1. **Download the Extension:** Download the latest release from the [Releases page] (or build it from source following the Developer guide below).
35
+2. **Open Extensions Page:** In Chrome, go to `chrome://extensions/`.
36
+3. **Enable Developer Mode:** Toggle the switch in the top right corner.
37
+4. **Load Unpacked:** Click the "Load unpacked" button and select the `opengrammar/extension/dist` folder you downloaded.
38
+5. **Configure:** Click the OpenGrammar icon in your browser toolbar. If you want advanced AI features, paste your OpenAI or OpenRouter API key here. It is saved locally on your device.
39
+
40
+---
41
+
42
+## 💻 Developer Guide: Build & Deploy
43
+
44
+Want to build OpenGrammar from scratch or deploy your own backend? Here is how.
45
+
46
+### Prerequisites
47
+
48
+- Node.js (v18 or newer)
49
+- npm, pnpm, or yarn
50
+
51
+### 1. Set up the Backend (Serverless Edge API)
52
+
53
+The backend is a lightweight API that securely handles the AI requests. It's designed to run on Cloudflare Workers (or Vercel Edge), which are incredibly fast and offer generous free tiers.
54
+
55
+```bash
56
+# Navigate to the backend folder
57
+cd opengrammar/backend
58
+
59
+# Install dependencies
60
+npm install
61
+
62
+# Run locally for testing (runs on http://localhost:8787)
63
+npm run dev
64
+
65
+# Deploy to Cloudflare Workers (requires a free Cloudflare account)
66
+npx wrangler deploy
67
+```
68
+*After deploying, copy the provided URL (e.g., `https://opengrammar.yourname.workers.dev`).*
69
+
70
+### 2. Set up the Chrome Extension
71
+
72
+```bash
73
+# Navigate to the extension folder
74
+cd opengrammar/extension
75
+
76
+# Install dependencies
77
+npm install
78
+
79
+# IMPORTANT: Link your Backend
80
+# Open src/background/index.ts and replace the BACKEND_URL with your deployed URL from step 1 (or leave as localhost for local testing).
81
+
82
+# Build the extension
83
+npm run build
84
+```
85
+
86
+This will create a `dist/` folder. Load this folder into Chrome following the "Getting Started (For Users)" instructions above.
87
+
88
+---
89
+
90
+## 🤝 Contributing
91
+
92
+OpenGrammar is a community effort! Whether you want to add new local grammar rules, improve the highlighting logic in rich text editors, or fix bugs, we welcome your contributions. Please check out our `ROADMAP.md` for inspiration.
93
+
94
+## 📄 License
95
+
96
+This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
0
97