Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,36 @@ Core invariants:
## Current implementation
The active MVP is a React/Vite browser workspace. State is in memory and there is no production persistence or publication backend. The browser can download and restore the exact deterministic schema-v1 JSON draft containing normalized operator-authored facts and readiness finding codes. Restore treats the local file as untrusted input, admits only the closed schema and catalog, and recomputes derived readiness evidence before atomically replacing workspace state. This local portability boundary is not publication, persistence, backup, or legal approval. The seven PRD steps are routed to distinct editing surfaces. The collection taxonomy is metadata only. `src/policy.ts` owns deterministic collection-selection/no-collection/mode/purpose/path, non-collection authoring-completeness findings, and schema-v1 validation/reconstruction; `src/App.tsx` owns browser orchestration, bounded local file selection, explicit no-collection and transfer-status capture, warning-to-source navigation, stale dependent-fact invalidation, and deterministic preview rendering. `src/AuthoringFocusController.tsx` is a browser interaction adapter: after explicit rail, previous/next, or review-warning navigation changes the active editing surface, it moves programmatic focus to that surface's heading without changing domain state, intercepting ordinary field interaction, or overriding the separate preview-focus shortcut.

The separate `src/policy-review-report.ts` read projection creates the local minimal TXT review summary via `createPolicyReviewText`. It consumes `createPolicyExport` for canonical service identity/state/ordered codes, `getCompletedSteps` for seven responsibility states, and `getReview` for recommendation labels; it is not a second readiness engine or aggregate. Each code keeps one row, with `단계 미상` fallback instead of data loss. Detailed path/purpose, retention, recipient/country and contact values are excluded; service identity remains disclosure-bearing. JSON quoting plus visible Unicode line/direction-control escaping applies at this TXT boundary, without claiming HTML/Markdown sanitization.

`App.tsx` owns the fixed-name `policyweave-review.txt` browser download, pending-import disable/handler guard, bounded failure feedback and next-task object-URL cleanup after allocation. Download initiation changes feedback only, not authored facts, navigation or readiness. Presentation `report_format: v1` is independent of fact `schema_version: 1` and neither is a publication revision. [ADR-0006](docs/ADR-0006-local-review-summary.md) records the choice; [local layered proposal/review evidence](docs/evidence/mixed-agents-review-summary.md) records the development workflow, not runtime product AI, heterogeneous-model verification or an approval receipt. No new network, storage, dependency or legal-rule boundary is introduced.

PRD `US-SESSION-01` exposes, rather than changes, that memory boundary. Shared `SessionNotice` is a static paragraph after the section heading and before inputs in all three editor component types, yielding one notice in each active step. It explains no automatic saving, reload/tab-close loss and the existing JSON export path without new live/focus ownership, a global layout row, browser storage, beforeunload or persistence adapter. Header/preview `앱 버전 0.1.0` is separate from fact `schema_version: 1`, report `report_format: v1` and any future publication revision. Import's existing polite pending status and semantic lock retain their own ownership; the notice neither alters facts/readiness nor certifies file storage. JSON carries admitted normalized facts, not a complete raw-input backup; TXT is a review projection, not a restore source. [The session evidence record](docs/evidence/session-notice-20261005.md) separates layered development, bounded TDD observations and unfinished current-candidate gates from historical receipts.

Authoring completeness is deliberately separate from legal sufficiency. Current readiness rules prove that product-defined fact responsibilities were explicitly addressed; they do not assert that a policy complies with law. Source/effective-date-bound legal validation belongs to the Legal Source Registry -> Review & Publication boundary.

## Canonical URL portability successor — 2026-10-05 candidate

Historical checkpoint note: the 03:18 KST pending/frozen-TXT statements below describe that checkpoint, not the later delivered URL slice. At 03:30 KST, an independently compiled retained predecessor/candidate comparison confirmed exact TXT bytes for eight previously admissible cases; rejected-URL output is intentionally excluded from that compatibility claim. The later [URL evidence](docs/evidence/url-portability-20261005.md) and PR #26 published head `1e662c2f08d4e156b9280ef434bc876c0c77b283` record completed local gates and whole-source review, not hosted acceptance or release. The subsequent [mobile-title evidence](docs/evidence/mobile-document-title-20261005.md) separately records a fullgate NONPASS and observation repair; it must not inherit the predecessor's runtime clearance.

The Policy Fact Authoring export boundary derives URL evidence from admitted normalized facts, not discarded raw diagnostics. `createPolicyExport` withholds a rejected URL as `null` and computes `service_url` against that admitted absence. The editor's raw `getDraftReview` still emits `service_url_format`; both remain incomplete and owned by step 1. The two views serve different correction/portability responsibilities and do not mutate one another. A JSON restore reconstructs only admitted facts and must recompute identical ordered codes/readiness; historical `null` + format evidence remains rejected, not grandfathered or migrated.

The TXT read projection supplies that same canonical URL (or empty sentinel) to the unchanged public `formatReviewFinding` helper. Thus canonical `service_url` has its step-1 label, while raw helper calls retain raw format lookup and unresolved-code fallback. One row per exported code, ordering, non-URL findings, completion and recommendation authority remain intact. This is not a second readiness engine or a raw-input backup. Fact schema 1/report format v1 are unchanged; prior blank/valid JSON/TXT byte preservation requires frozen-fixture verification. Initially pending, the JSON blank/valid direct-export and restore/re-export comparisons plus withheld strict denial are parent-reported confirmed at 03:18 KST; frozen TXT comparison remains unverified.

[The dated successor evidence](docs/evidence/url-portability-20261005.md) binds Layer1 proposals/runtime RED, summary-fed Layer2 conditional reviews and parent aggregation separately from intermediate focused GREEN and unfinished current full/browser/whole-prior-PR-union review/hosted acceptance. Parent 03:18 KST successor reports 65 focused cases plus lint/build against the owned source/test freeze, still not full-suite acceptance. No persistence, UI, autosave, network or legal-source boundary is changed; separate cancellation/stream and centralized workflow owners are not overlaid.

## Mobile document-title presentation boundary — 2026-10-05 candidate

PRD `US-MOBILE-TITLE-01` places the mobile header's existing document-name text on a normal-flow wrapping row. The implementation candidate is limited to the `.document-name` rule inside `max-width: 720px`; `App.tsx` retains the exact service-name projection, policy suffix and DOM order. Title layout has no fact, readiness, focus, download, importer or persistence authority. Natural header-height growth is intentional, while existing visible sibling controls must remain readable and nonoverlapping. Default/short-name nonmobile layout is a preservation boundary; global long-name/preview reflow is not included. [The dated evidence](docs/evidence/mobile-document-title-20261005.md) separates current diagnostics and planning from uncompleted implementation and final acceptance. Existing ADR-0005/0006 contracts are unchanged; no new architecture or legal decision is introduced.

## Mobile import-feedback presentation boundary — 2026-10-05 candidate

PRD `US-IMPORT-FEEDBACK-01` repairs mobile exposure of the existing `.save-state` polite region through stylesheet presentation only. A normal-flow wrapping row exposes pending and idle copy without new App state, DOM/live owner, import authority or persistence adapter. Fieldset busy and existing import/authoring/TXT locks remain; busy must not defer the live region through its ancestors. Static SessionNotice remains outside live ownership. Status has no fact/readiness/file-storage authority. Default/short-name nonmobile layout and the existing mobile title rule are preservation boundaries. [Dated evidence](docs/evidence/mobile-import-feedback-20261005.md) distinguishes baseline diagnostics and layered planning from incomplete repository TDD/final acceptance. ADR-0005/0006, separate cancellation/stream work and hosted integration gates are unchanged; no new legal or architecture decision is introduced.

## Screen preview reading-width boundary — 2026-10-05 candidate

PRD `US-PREVIEW-REFLOW-01` is a screen-presentation convenience contract for existing deterministic fact text. Direct paper h2/p and table th/td share a scoped wrapping declaration; warning controls, fixed clause headings and print media are excluded. It adds no facts, readiness engine, state owner, focus/live region, file format or persistence authority. Existing horizontal access was demonstrated, so the candidate is not lost-data recovery. Natural vertical growth/scrolling remains valid. [Dated evidence](docs/evidence/preview-text-reflow-20261005.md) distinguishes actual diagnostic access and layered planning from pending repository TDD and final acceptance. ADR-0005/0006 normalized portability/minimal TXT boundaries remain unchanged; no new legal or hosted architecture decision is introduced.

## Persistence boundary (Proposed schema; CI-only runtime)
ADR-0003 and `db/migrations/0001_policy_revision.sql` propose the first PostgreSQL contract. The 3NF write model uses `policy_revision` as aggregate root; `service_profile`, `collection_item`, `processing_purpose`, and `retention_rule` are revision-owned facts. `(tenant_account_id, revision_number)` identifies a version, while `(policy_revision_id, collection_item_key)` is the item-level UPSERT/idempotency key. Deferred database constraints lock the owning revision row, reject collection items under explicit no-collection, and reject retention-rule/status contradictions at transaction commit.

Expand Down
Loading
Loading