Build Grammarly

KINDAreplaces $30/mosaves $360/yrback to the verdict

0%0 of 23 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

Build a local writing checker with rule suggestions and optional accepted rewrites.

estimated effort multi-daythe files for this build are in the project pack

RuntimePython 3.12+ and FlaskStorageSQLite through Python sqlite3InterfaceJinja HTML templates, CSS and vanilla JavaScriptVerificationPython unittest and browser acceptance fixturesGenerationOllama local HTTP APIGrammarLanguageTool Java HTTP server

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

installPython is free; this local prototype requires no hosting subscription.
Why The local backend, tests and storage use Python.
Get it Install Python from python.org. Open a terminal in a new empty project folder. On Windows, use py -3 where this guide says python if python is not on PATH; on macOS/Linux use python3 if needed. Create .venv and activate it before installing packages. open ↗
Verify python --version reports 3.12+ and python -c "import sqlite3" succeeds.
installNo paid service required for this local step.
Why You need to view the local interface and edit generated project files.
Get it Use an installed Chrome, Firefox or Edge browser. Open the empty project folder in your editor; open the terminal there, not in this catalog repository.
Verify You can create a text file in the project folder and open browser developer tools.
have readyNo paid service required for this local step.
Why This fixture makes the first end-to-end check reproducible.
Get it Create synthetic sample data before implementation: A short paragraph with a misspelling, an emoji before it and a protected proper name. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records.
Verify The fixture files and expected outcomes exist and can be inspected without a vendor account.
decideNo paid service required for this local step.
Why The full commercial product is larger than this guide.
Get it The deliverable is a local writing checker with rule suggestions and optional accepted rewrites. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first.
Verify You can name the primary workflow and the vendor features this version deliberately leaves out.
installNo cloud inference fee for this local configuration; you supply disk space, compute and electricity.
Why Generation requires a running model; ordinary editing remains usable while it is unavailable.
Get it Install Ollama from the official site, choose a locally runnable model from its library that fits available RAM, download it, and copy its exact installed name into LOCAL_MODEL. Use the documented local-only configuration, exclude cloud model names, and record model license, download size and tested memory use. open ↗
Verify ollama list shows the chosen model; a short local prompt succeeds with network access disabled after download.
installLocal basic engine; premium cloud-only rules are outside this build.
Why The app reuses the existing grammar engine.
Get it Follow the official server page: install a compatible Java runtime, download and unzip the LanguageTool server distribution, create server.properties, then start the server using the command in the first phase. Do not install an assumed official Docker image. open ↗
Verify java -version succeeds and http://localhost:8081/v2/check?language=en-US&text=my+text returns JSON.

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- documents(id,title,text,revision)
- issues(id,document_id,revision,offset,length,rule_id,message,replacements_json)
- dictionary(word)
- rewrites(id,document_id,revision,mode,proposal,state)
- Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them.
- Acceptance fixture: A short paragraph with a misspelling, an emoji before it and a protected proper name.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

Variable	Needed	Example	Where the value comes from
`DATA_DIR`	required	`./data/grammarly`	A new private folder this application creates on first run; never serve it as static files.
`SECRET_KEY`secret	required	`replace-with-a-random-secret`	Generate with python -c "import secrets; print(secrets.token_hex(32))" and save only in .env.
`APP_MODE`	required	`indie`	Use indie for loopback-only personal work. Product mode must refuse to start until owner login and the deployment gates are configured.
`SITE_URL`	required	`http://127.0.0.1:5000`	The origin used for local forms and links; replace with the chosen HTTPS origin in product mode.
`OLLAMA_URL`	required	`http://127.0.0.1:11434`	Keep the inference service bound to loopback; the backend calls it, never the public browser.
`LOCAL_MODEL`	optional	`replace-with-installed-local-model`	Copy the exact non-cloud name from ollama list; preflight must reject this placeholder.
`LANGUAGETOOL_URL`	required	`http://127.0.0.1:8081`	The loopback Java server started from the official distribution; Python proxies checks to it.

The build, in order

1
Local foundation and data contract
Create the runnable local foundation for a local writing checker with rule suggestions and optional accepted rewrites, including the real schema and acceptance fixture.
1. Run the venv command first, then stop and activate it before running the remaining commands. Use your OS instructions: Windows .venv\Scripts\activate.bat in cmd, or .venv\Scripts\Activate.ps1 in PowerShell; macOS/Linux source .venv/bin/activate. Then install the listed packages. Create app.py exposing app, load .env with python-dotenv, and add a /healthz route. Freeze tested dependency versions to requirements.txt. Create .env manually from .env.example; replace SECRET_KEY before launch.
  Files app.pyrequirements.txt.env.example.gitignore
  terminal
  python -m venv .venv python -m pip install Flask Flask-WTF python-dotenv waitress tzdata python -m pip freeze > requirements.txt python -m flask --app app run --host 127.0.0.1
2. For database-backed state create schema.sql and db.py using this model: documents(id,title,text,revision); issues(id,document_id,revision,offset,length,rule_id,message,replacements_json); dictionary(word); rewrites(id,document_id,revision,mode,proposal,state). Add the auxiliary relationships explicitly used in later phases; use stable ids, foreign keys, parameterized values and transactions. For canonical files use atomic replacement and hashes instead. Implement python manage.py init and python manage.py seed to create only synthetic data: A short paragraph with a misspelling, an emoji before it and a protected proper name. Re-running init must not erase data.
  Files schema.sqldb.pymanage.pyfixtures/README.md
  terminal
  python manage.py init python manage.py seed
3. Install Flask-WTF CSRF protection for forms and same-origin fetches, validate Host and Origin against SITE_URL, bound inputs and escape output. Deliberately public intake endpoints get bounded validation and rate limits; signed provider webhooks use signature checks instead of browser CSRF tokens. All other admin routes stay local until product authentication exists. When a later phase tests viewer/member permissions, implement the users, hashed passwords, expiring server sessions and role checks in this foundation first; product mode must never use a fabricated identity from request input. Add error, empty, keyboard-focus and retry states now.
  Files app.pytemplates/base.htmltest/test_foundation.py
4. Create providers/local_model.py with a POST /api/chat adapter using the configured local model and stream:false. Validate structured output, bound input/output, set a timeout and reject cloud models or non-loopback inference URLs. Add a probe that sends one harmless prompt and a test double for deterministic tests. Missing model setup must disable generation with a specific error while leaving editing usable.
  Files providers/local_model.pyscripts/model_probe.py
  terminal
  python scripts/model_probe.py
5. In the unzipped LanguageTool distribution create an empty server.properties and run the command below in a separate terminal. Keep the default local-only binding and proxy requests through Python; no browser-wide CORS permission is needed.
  Files providers/grammar.py
  terminal
  java -cp languagetool-server.jar org.languagetool.server.HTTPServer --config server.properties --port 8081
done when · tick each as it passes
watch out
- The Flask development server is for local development only. Loopback binding alone does not replace CSRF and origin validation.
next phase
2
Local grammar service
Local grammar service for Grammarly: Start the LanguageTool Java HTTP server locally from the official distribution and connect through the Python backend using POST /v2/check.
1. Start the LanguageTool Java HTTP server locally from the official distribution and connect through the Python backend using POST /v2/check.
  Files features/local_grammar_service.pytemplates/local_grammar_service.html
2. Record the input revision with returned offsets; show explicit language selection and ignore configured dictionary words.
  Files features/local_grammar_service.py
3. Use A short paragraph with a misspelling, an emoji before it and a protected proper name. Check: A check returns a visible issue on the deliberate misspelling. Then check: Disconnecting the service shows retry guidance without deleting the draft. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.
  Files test/test_local_grammar_service.py
  terminal
  python -m unittest discover -s test
done when · tick each as it passes
watch out
- The local server supplies basic rules; cloud-only AI checks are not included.
next phase
3
Safe inline replacement
Safe inline replacement for Grammarly: Map LanguageTool offsets to browser string positions carefully and highlight the fixture error after an emoji.
1. Map LanguageTool offsets to browser string positions carefully and highlight the fixture error after an emoji.
  Files features/safe_inline_replacement.pytemplates/safe_inline_replacement.html
2. Apply one suggestion only if the document revision still matches, then rerun checking rather than shifting all saved offsets.
  Files features/safe_inline_replacement.py
3. Use A short paragraph with a misspelling, an emoji before it and a protected proper name. Check: Accepting the correction changes only the intended word after the emoji. Then check: Editing the draft during a check invalidates stale suggestions. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.
  Files test/test_safe_inline_replacement.py
  terminal
  python -m unittest discover -s test
done when · tick each as it passes
watch out
- Offset conventions across Java, Python and JavaScript can differ around non-BMP characters.
next phase
4
Optional rewrite and CLI
Optional rewrite and CLI for Grammarly: Add optional local-model tighten/friendlier/formal modes with side-by-side diff and explicit acceptance.
1. Add optional local-model tighten/friendlier/formal modes with side-by-side diff and explicit acceptance.
  Files features/optional_rewrite_and_cli.pytemplates/optional_rewrite_and_cli.html
2. Expose a check-file CLI using the same service and dictionary, with nonzero exit when issues remain.
  Files features/optional_rewrite_and_cli.py
3. Use A short paragraph with a misspelling, an emoji before it and a protected proper name. Check: Rejecting a rewrite preserves the original document exactly. Then check: The CLI returns a failure status for the misspelling fixture and success after correction. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.
  Files test/test_optional_rewrite_and_cli.py
  terminal
  python -m unittest discover -s test
done when · tick each as it passes
watch out
- This is a destination editor; system-wide inline checking and proprietary tone models are not reproduced.
next phase
5
Portable delivery and clean-start proof
Finish the Grammarly replacement with a documented first-run path and a recoverable export.
1. Document prerequisites, every configuration variable, data locations and the three domain workflows: Local grammar service; Safe inline replacement; Optional rewrite and CLI. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them.
  Files README.md.env.example
2. Use sqlite3.Connection.backup for the database in DATA_DIR and pause writers while taking the matching attachment snapshot. Keep schema version, hashes and a manifest for grammarly. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A short paragraph with a misspelling, an emoji before it and a protected proper name. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy.
  Files OPERATIONS.mdscripts/backup.py
3. Use a new folder and only README instructions to reach the fixture outcome. Install from requirements.txt, initialize storage, run the tests and exercise the UI at 375px and 1280px; use keyboard-only controls and inspect browser errors. Record exactly what passed; do not mark unrun checks complete.
  Files README.mdverification.md
  terminal
  python -m pip install -r requirements.txt python -m unittest discover -s test
done when · tick each as it passes
watch out
- Export without an import or restore rehearsal is not verified portability.
6
Operate and share with access controlsproduct builder
Product-builder only: make a local writing checker with rule suggestions and optional accepted rewrites operable for its stated audience before allowing remote access.
1. Add owner/member/viewer authorization as appropriate, password hashes through Werkzeug, expiring server-side sessions, CSRF and login rate limits. Add users, sessions and audit schema migrations plus an owner-init command prompting securely for its password. Enforce ownership on every private read/write/download and fail closed when product setup is incomplete. Existing learner or admin identities must use this same boundary.
  Files ARCHITECTURE.mdOPERATIONS.md
2. Serve app:app with Waitress on loopback behind Caddy HTTPS. Configure trusted proxy headers narrowly, Secure/HttpOnly/SameSite cookies, upload limits, request ids and structured logs without private content. Run background jobs as a separate supervised process when the domain workflow requires them.
  Files CaddyfileOPERATIONS.md
  terminal
  waitress-serve --listen=127.0.0.1:5000 app:app
3. Add a scheduled encrypted off-host backup using this procedure: Use sqlite3.Connection.backup for the database in DATA_DIR and pause writers while taking the matching attachment snapshot. Keep schema version, hashes and a manifest for grammarly. Monitor health, disk space, failed jobs and backup age. Stop the service to test an alert; rehearse recovery with outbound effects disabled and record recovery time. Rotate any exposed credentials and require reconciliation before resuming queues.
  Files OPERATIONS.mdrelease-checklist.md
done when · tick each as it passes
watch out
- Product mode is additional engineering, not a switch that makes a local prototype production-ready.

what this build does not replace

This is a destination editor; system-wide inline checking and proprietary tone models are not reproduced.
This is a local writing checker with rule suggestions and optional accepted rewrites; full Grammarly feature parity, vendor hosting and support are not included.
inline suggestions everywhere
document/email integrations
tone/brand controls
enterprise admin
polished false-positive handling

after v1, if you want it

Extend optional rewrite and cli only after the fixture and recovery checks pass.
Before adding another integration, document its credentials, limits, cost and failure behavior with primary-source links.

Need the files? The project pack on the verdict page hands your agent the whole brief · more ai writing.