67 lines
4.4 KiB
Markdown
67 lines
4.4 KiB
Markdown
# Decisions
|
|
|
|
> Lightweight ADRs (Architecture Decision Records). One entry per material decision: what was decided, why, what was rejected, and when. Newest at the top. Never rewrite history — supersede instead.
|
|
|
|
## How to use
|
|
|
|
Add an entry when a choice is hard to reverse, shapes future work, or a future maintainer would otherwise ask "why is it like this?" Skip trivial or easily reversible choices. When a decision is replaced, set the old entry's status to `superseded by [ID]` rather than deleting it.
|
|
|
|
## Decision template
|
|
|
|
```markdown
|
|
### D-YYYY-MM-DD-NN — [short decision title]
|
|
|
|
- **Status:** proposed | accepted | superseded by [ID] | reversed
|
|
- **Context:** [the forces and constraints that made a decision necessary]
|
|
- **Decision:** [what we chose, stated plainly]
|
|
- **Alternatives considered:** [options rejected, with the reason each lost]
|
|
- **Consequences:** [what this makes easy, what it makes hard, new risks]
|
|
- **Verification:** [how we'll know it was right — metric, test, or review date]
|
|
- **Owner / date:** [who decided, when]
|
|
```
|
|
|
|
## Log
|
|
|
|
### D-2026-09-04-01 — Commit each landed task; graphify update at session end
|
|
|
|
- **Status:** accepted
|
|
- **Context:** Graph and git lagged behind work (SEO sat uncommitted; graph needed a manual deep rebuild).
|
|
- **Decision:** After every completed task, commit landed files (never secrets or `graphify-out/`). Do not push unless asked. At session end, run `graphify update .`.
|
|
- **Alternatives considered:** Commit only when asked (lost work); full `/graphify --mode deep` every session (too expensive).
|
|
- **Consequences:** More small commits on `dev`. Graph stays AST-current; docs/images still need an occasional deep extract.
|
|
- **Verification:** Session-start hook reminds the workflow; `graphify-out/` stays gitignored.
|
|
- **Owner / date:** John Kevin, 2026-09-04
|
|
|
|
### D-2026-09-03-01 — Website path URLs for Google indexing
|
|
|
|
- **Status:** accepted
|
|
- **Context:** The marketing site used HashRouter (`/#/docs`). Google does not treat hash fragments as indexable URLs. Production already had SPA fallbacks.
|
|
- **Decision:** Switch to BrowserRouter; prerender unique HTML for `/`, `/docs`, `/contribute`, `/community`; ship `/robots.txt` and `/sitemap.xml`; unknown paths return HTTP 404; rewrite legacy `#/…` hashes on load.
|
|
- **Alternatives considered:** Keep hashes (rejected: not crawlable as pages); full SSR (rejected: extra stack for a static brochure).
|
|
- **Consequences:** Coolify/nginx must keep SPA fallback for the four routes. Old social posts with `#/docs` still work via the hash rewrite.
|
|
- **Verification:** `npm run website:build`; GET `/robots.txt`, `/sitemap.xml`, `/docs` 200 with unique titles; GET `/no-such-page` 404.
|
|
- **Owner / date:** John Kevin / lead, 2026-09-03
|
|
|
|
### D-2026-08-13-01 — VS Code port: shared `src/lib` + native v1 UX
|
|
|
|
- **Status:** accepted
|
|
- **Context:** Need a VS Code twin of LexAI without forking provider/prompt logic or blocking the Chrome WXT app.
|
|
- **Decision:** Keep Chrome at repo root; add `packages/vscode` that esbuild-bundles `@lib/providers|actions|types`. v1 uses Command Palette + editor context submenu + `lexai.*` settings + Secret Storage for the API key. Defer floating toolbar, Prompt Builder UI, Copy As, and relocating Chrome into `packages/chrome`.
|
|
- **Alternatives considered:** Separate repo (rejected: prompt/provider drift); full npm workspaces + move Chrome (rejected: high break risk for WXT); Chrome-like webview toolbar in v1 (rejected: slower path to usable editor replace).
|
|
- **Consequences:** One prompt/provider source of truth; two settings stores (not synced); VS Code feature gap vs Chrome until a later phase.
|
|
- **Verification:** `npm run vscode:typecheck` + `npm run vscode:build`; manual F5 / VSIX select→replace smoke.
|
|
- **Owner / date:** John Kevin / lead, 2026-08-13
|
|
|
|
|
|
<!--
|
|
### D-2026-01-01-01 — Example: choose Postgres over a document store
|
|
|
|
- **Status:** accepted
|
|
- **Context:** Core data is highly relational; we need transactions and ad-hoc queries.
|
|
- **Decision:** Use PostgreSQL as the primary datastore.
|
|
- **Alternatives considered:** MongoDB (rejected: relational joins would be app-side and error-prone); SQLite (rejected: concurrent write ceiling).
|
|
- **Consequences:** Strong consistency and rich querying; adds an ops dependency and migration discipline.
|
|
- **Verification:** Load test the core query path; revisit if write contention appears.
|
|
- **Owner / date:** [name], 2026-01-01
|
|
-->
|