docs: bootstrap .planning/ via /gsd-ingest-docs (2 docs) /home/parf/projects/work/repremium/.planning/PROJECT.md /home/parf/projects/work/repremium/.planning/REQUIREMENTS.md /home/parf/projects/work/repremium/.planning/ROADMAP.md /home/parf/projects/work/repremium/.planning/STATE.md /home/parf/projects/work/repremium/.planning/intel /home/parf/projects/work/repremium/.planning/INGEST-CONFLICTS.md /home/parf/projects/work/repremium/.ingest-manifest.yaml
This commit is contained in:
180
.planning/intel/decisions.md
Normal file
180
.planning/intel/decisions.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Architectural Decisions (synthesized from SPEC)
|
||||
|
||||
The SPEC `Тз расширение фаза1.md` does not formally label itself as ADR-set, but
|
||||
sections 2 ("Стек"), 7 ("Разрешения в manifest.json"), and 8 ("Важные
|
||||
ограничения и решения") encode binding technical choices that act as
|
||||
architectural decisions for Phase 1. Each decision below is reproduced from the
|
||||
SPEC verbatim where possible and tagged with its origin.
|
||||
|
||||
Status legend (synthesized, since SPEC has no formal ADR status field):
|
||||
- `Accepted` — SPEC §2/§7/§8 prescribed, no contradicting source
|
||||
- `locked: false` everywhere — SPEC is `locked: false` in classification, so
|
||||
these decisions can still be revised by a future ADR; today they are the
|
||||
authoritative baseline.
|
||||
|
||||
---
|
||||
|
||||
## DEC-001: Chrome Extension Manifest V3
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2 (Стек), §7 (Разрешения)
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Extension platform / packaging
|
||||
- Decision: The extension MUST be implemented as a Chrome Extension targeting
|
||||
Manifest V3 (Service Worker background, no persistent background page).
|
||||
- Rationale (from SPEC): Required for modern Chrome compatibility; implied by
|
||||
every API used (`chrome.tabCapture`, `chrome.downloads`, `chrome.tabs`,
|
||||
`chrome.alarms`).
|
||||
- Confirming source: `README.md` §"Технический стек" — "Chrome Extension,
|
||||
Manifest V3".
|
||||
|
||||
---
|
||||
|
||||
## DEC-002: Service Worker as Background Coordinator
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2, §3 (Структура расширения), §8
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Background execution model
|
||||
- Decision: Background logic runs in a Manifest V3 Service Worker
|
||||
(`background/service-worker.js`) that coordinates the video buffer and
|
||||
archive packaging.
|
||||
- Constraint binding: Service Worker is unloaded after ~30 s idle; keepalive
|
||||
MUST be maintained via `chrome.alarms` firing every 20 seconds (SPEC §8).
|
||||
- Confirming source: `README.md` §"Технический стек".
|
||||
|
||||
---
|
||||
|
||||
## DEC-003: Tab Video Capture via `chrome.tabCapture`
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2, §4.1, §7
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Video acquisition
|
||||
- Decision: Active-tab video is captured via `chrome.tabCapture.capture()`.
|
||||
- Codec/bitrate binding: `video/webm; codecs=vp9` at `400 000 bps`.
|
||||
- `MediaRecorder` chunk cadence: 2000 ms.
|
||||
- Activation constraint: `tabCapture` is tied to the active tab and requires a
|
||||
user gesture on first invocation; on tab switch the capture re-attaches.
|
||||
- Confirming source: `README.md` §"Технический стек".
|
||||
|
||||
---
|
||||
|
||||
## DEC-004: DOM Capture via rrweb
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2, §4.2
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: DOM recording
|
||||
- Decision: DOM events are captured via the `rrweb` npm library
|
||||
(`rrweb.record()`), running in the Content Script, with events forwarded to
|
||||
the Service Worker on archive-export request.
|
||||
- Sensitive-data binding: rrweb is configured with `maskInputSelector` to mask
|
||||
`input[type=password]` and `[data-sensitive="true"]`.
|
||||
- Buffer cap binding: 5 000 rrweb events maximum; oldest dropped on overflow
|
||||
(SPEC §8).
|
||||
- Confirming source: `README.md` §"Технический стек", §"Особенности".
|
||||
|
||||
---
|
||||
|
||||
## DEC-005: Archive Packaging via JSZip
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2, §3, §6
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Archive assembly
|
||||
- Decision: ZIP packaging uses the `jszip` npm library bundled as
|
||||
`libs/jszip.min.js` (or the Vite-bundled equivalent).
|
||||
- Archive layout binding: see REQ-archive-layout in `requirements.md`.
|
||||
- Confirming source: `README.md` §"Технический стек".
|
||||
|
||||
---
|
||||
|
||||
## DEC-006: File Download via `chrome.downloads`
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2, §5, §7
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: File delivery
|
||||
- Decision: The assembled ZIP is delivered to the user's "Downloads" folder via
|
||||
`chrome.downloads.download()`. No server upload in Phase 1.
|
||||
- Confirming source: `README.md` §"Технический стек".
|
||||
|
||||
---
|
||||
|
||||
## DEC-007: In-Memory Buffers in Service Worker + Content Script
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §2, §4.1, §4.2, §4.3
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Storage strategy
|
||||
- Decision: All recorded data (video chunks, rrweb events, user-event log) is
|
||||
held in memory only — video chunks in the Service Worker, rrweb events and
|
||||
user-event log in the Content Script. No `chrome.storage` / IndexedDB
|
||||
persistence for the rolling buffers in Phase 1.
|
||||
- Confirming source: `README.md` §"Технический стек" — "In-memory (Service
|
||||
Worker + Content Script)".
|
||||
|
||||
---
|
||||
|
||||
## DEC-008: Screenshot via `chrome.tabs.captureVisibleTab`
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §4.4, §5
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Screenshot capture
|
||||
- Decision: A single PNG screenshot is captured via
|
||||
`chrome.tabs.captureVisibleTab()` at the moment the user clicks "Save
|
||||
archive". The screenshot is bundled as `screenshot.png` inside the ZIP.
|
||||
|
||||
---
|
||||
|
||||
## DEC-009: WebM Header Retention
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §4.1, §8
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Video container integrity
|
||||
- Decision: The first chunk emitted by `MediaRecorder` (which contains the WebM
|
||||
container header) MUST be retained in the ring buffer indefinitely; only
|
||||
subsequent chunks rotate out by the 30-second TTL rule.
|
||||
- Rationale (from SPEC §8): WebM without its header is not playable.
|
||||
|
||||
---
|
||||
|
||||
## DEC-010: Service Worker Keepalive via `chrome.alarms`
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §8
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Service Worker lifecycle
|
||||
- Decision: To prevent the 30 s idle unload of MV3 Service Workers, a
|
||||
`chrome.alarms` alarm fires every 20 seconds to keep the worker alive.
|
||||
|
||||
---
|
||||
|
||||
## DEC-011: Manifest Permissions Set
|
||||
|
||||
- Source: `Тз расширение фаза1.md` §7
|
||||
- Status: Accepted
|
||||
- Locked: false
|
||||
- Scope: Manifest configuration
|
||||
- Decision: `manifest.json` requests exactly:
|
||||
- `permissions`: `tabCapture`, `activeTab`, `downloads`, `scripting`,
|
||||
`storage`
|
||||
- `host_permissions`: `<all_urls>`
|
||||
- Note: `tabCapture` requires explicit user gesture on first activation.
|
||||
|
||||
---
|
||||
|
||||
## DEC-012: Vite + crxjs + TypeScript Build Toolchain
|
||||
|
||||
- Source: `README.md` §"Технический стек"
|
||||
- Status: Accepted (DOC-level — not asserted by SPEC)
|
||||
- Locked: false
|
||||
- Scope: Build tooling
|
||||
- Decision: The extension is built with Vite + the `crxjs` plugin in
|
||||
TypeScript. The SPEC does not prescribe a build tool, so this is a
|
||||
DOC-level decision not contradicted by any higher-precedence source.
|
||||
- Provenance caveat: If a future ADR/SPEC selects a different toolchain, this
|
||||
DEC is auto-overridden.
|
||||
Reference in New Issue
Block a user