Loading module
Resolving locale, route permissions, and workspace projection.
EX-PL-01 UI TRANSLATION SPECIFICATION
Document Type: Governance-to-UI Implementation Bridge
Procedure: EX-PL-01 — Land Plot Registration & Verification
Status: DRAFT — NON-AUTHORITATIVE INPUT
Version: 1.0
Date: 2026-02-09
1. Purpose & Scope
This document translates governance state logic from:
EX-PL-01-GOVERNANCE-WALKTHROUGH.md
Into UI-implementable specifications that:
- Preserve governance constraints
- Enable frontend development
- Do NOT violate independence, confidentiality, or neutrality rules
This document is NOT:
- A final UI design
- A component library
READ 2026-03-28T23:42:21.903Z
READ 2026-03-29T04:52:41.869Z
CORE STRICT SAFE DELETE AFTER RERUN REPORT
PUBLIC | DRAFT | v1.0.0
READ 2026-03-29T03:13:33.020Z
A backend specificationA workflow engine design
- A translation layer between governance and UI
- A compliance checklist for frontend developers
- A set of MANDATORY rules for UI rendering
Authority:
This document is subject to governance ratification and MUST NOT be treated as final.
2. Translation Principles
2.1 State as Single Source of Truth
- UI components MUST query governance state as the authoritative source
- UI MUST NOT derive or infer states
- UI MUST NOT cache state in a way that bypasses governance
2.2 Role-Based Rendering
- UI MUST check current user role before rendering any element
- UI MUST hide elements not allowed for that role
- UI MUST NOT rely on client-side role checks for security (backend authorization required)
2.3 Copy Compliance
- All UI text MUST be validated against allowed/prohibited wording lists
- UI MUST NOT dynamically generate copy that could violate governance
- Hard-coded strings MUST be auditable and traceable to this spec
2.4 Blockchain Presentation Constraints
- Blockchain references MUST be labeled as: "Anchoring Proof", "Settlement Reference"
- Blockchain MUST NOT be described as: "Executor", "Validator", "Controller"
- Blockchain icons/links MUST link to block explorers (read-only proof)
3. State-to-UI Mapping Table
| Governance State | UI Status Label | Allowed User Actions | Visible Information | Hidden Information |
|------------------|-----------------|---------------------|---------------------|-------------------|
| DRAFT | "Draft" | Edit, Delete, Submit | Plot ID, Cadastral Code, Owner input fields | Verifier info, verification criteria |
| SUBMITTED | "Submitted" | View only | Submission timestamp, Reference ID | Assigned verifier, routing logic |
| UNDER_VERIFICATION | "Under verification" | View status only | Submission date, Reference ID | Verifier identity, progress, partial results |
| VERIFICATION_COMPLETED | "Verification completed" | View outcome, Next action (if applicable) | Decision outcome, Next steps | Verifier identity, scoring details |
| CORRECTION_REQUIRED | "Correction required" | Edit specific fields, Resubmit | Correction items, Resubmit button | Internal reasoning, verifier notes |
| REGISTERED | "Registered" | View, Use in procedures | Registration ID, Anchoring proof, Plot details | Verification history details (unless audit permits) |
| DECLINED | "Registration declined" | View reason (if provided), Contact support | Formal decline reason (if disclosed) | Internal evaluation, verifier identity |
| CANCELLED | "Cancelled" | None (terminal) | Cancellation timestamp | Internal cancellation reason |
4. UI Component Requirements by State
4.1 DRAFT State UI
- Status badge: "Draft"
- Input fields for:
- Cadastral Code
- Registry Record Number
- Registry Date
- Document upload (PDF)
- Buttons: "Save Draft", "Delete Draft", "Submit for Verification"
- Progress bar
- "Approval likelihood" indicator
- Verifier assignment preview
- Heading: "Land Plot Registration (Draft)"
- Description: "Prepare land plot information for platform verification"
- Submit button: "Submit for Verification" (NOT "Submit for Approval")
4.2 SUBMITTED State UI
- Status badge: "Submitted"
- Read-only display of:
- Cadastral Code
- Registry Record Number
- Reference ID
- Submission timestamp
- Informational text: "Registration submitted for review"
- Edit button
- Cancel button (unless governed)
- Estimated completion time
- Progress indicator
- MUST use: "Submitted for review", "Under review"
- MUST NOT use: "Being approved", "In approval queue"
4.3 UNDER_VERIFICATION State UI
- Status badge: "Under verification"
- Read-only display of plot details
- Neutral informational text: "Platform verification in progress"
- Verifier name or photo
- Progress percentage
- Time remaining
- "Almost done" messages
- MUST use: "Verification in progress", "Under verification"
- MUST NOT use: "Being validated", "Final review stage"
Blockchain Anchoring (if displayed):
- Label: "Anchoring: Pending" (if not yet anchored)
- MUST NOT imply that anchoring is part of verification decision
4.4 VERIFICATION_COMPLETED State UI
- Status badge: "Verification completed"
- Decision outcome display (based on outcome)
- Conditional next actions
If outcome is VERIFIED → REGISTERED:
- Show: "Registered in platform registry"
- Enable: "View Registered Plot", "Use in Inspection Application"
If outcome is CORRECTION_REQUIRED:
- Show: "Correction required"
- Show: List of items to correct (if provided)
- Enable: "Edit and Resubmit"
- Show: "Registration declined"
- Show: Formal reason (if disclosed)
- Enable: "Contact Support" (if governance permits)
- Verifier identity
- Internal scoring breakdown
- Comparison to other applications
4.5 REGISTERED State UI
- Status badge: "Registered"
- Full read-only plot details
- Anchoring proof section:
- Algorand transaction link (if available)
- BNB Chain transaction link (if available)
- Hash values (SHA-256 / Keccak)
- Allowed actions: "Use in Inspection Application"
- Section heading: "Anchoring Proof"
- Label for Algorand: "Anchored on Algorand" + block explorer link
- Label for BNB: "Anchored on BNB Chain" + block explorer link
- MUST NOT use: "Blockchain Approval", "Smart Contract Confirmation"
Legal Disclaimer (MANDATORY):
UI MUST display a disclaimer such as:
"Platform registration does not constitute legal ownership confirmation or property rights certification. For legal matters, consult the Public Registry of Georgia or a licensed legal professional."
Exact wording: UNDEFINED — requires organizational and legal approval
- MUST use: "Registered in platform registry", "Available for platform use"
- MUST NOT use: "Ownership approved", "Land rights confirmed"
4.6 DECLINED State UI
- Status badge: "Registration declined"
- Neutral description: "Verification completed — registration not approved"
- Formal decline reason (if governance permits disclosure)
- Optional: "Contact Support" link
- Resubmit button (unless governance permits)
- "Try again" messaging
- Comparison to successful applications
- MUST use: "Registration declined", "Not registered"
- MUST NOT use: "Failed", "Rejected", "Ineligible"
4.7 CANCELLED State UI
- Status badge: "Cancelled"
- Neutral description: "Registration cancelled by request"
- Cancellation timestamp
- No action buttons
- "Restore" or "Undo" button (unless governance permits)
- MUST use: "Cancelled", "Registration withdrawn"
- MUST NOT use: "Deleted", "Removed"
5. Role-Specific UI Rules
5.1 LAND_OWNER UI Rules
- View own land plot status
- Edit plots in DRAFT or CORRECTION_REQUIRED states
- Submit for verification
- View registered plots
- View anchoring proof (if registered)
- View other land owners' plots (unless public by policy)
- View verifier identity or internal notes
- Modify plots in SUBMITTED, UNDER_VERIFICATION, or REGISTERED states
- UI MUST apply state-based action availability
- UI MUST NOT show disabled actions without explanation
- UI MUST NOT hide errors or rejections
5.2 VERIFIER UI Rules
- View assigned land plots
- Fill verification forms
- Submit verification decision (accept, decline, request correction)
- Upload verification evidence
- View plots not assigned to them
- Modify land owner-submitted data
- Override governance state transitions
- See other verifiers' decisions (unless governance permits)
- UI MUST check for conflict of interest before showing plot
- UI MUST NOT allow verifier to self-assign
5.3 PLATFORM_ADMIN UI Rules
- View all land plots (logged)
- Assign plots to verifiers
- View audit logs (read-only)
- Make verification decisions
- Modify submitted evidence
- Bypass governance approvals
- UI MUST show audit log viewer (read-only, timestamped, immutable presentation)
5.4 GOVERNANCE_MANAGER UI Rules
- View all land plots and full audit trail
- Initiate CAPA or management review
- Override assignments (logged)
- Directly approve or verify plots
- Modify completed verification decisions
6. Blockchain Anchoring UI Specification
6.1 Anchoring Proof Display
- ONLY in REGISTERED state
- MAY show in VERIFICATION_COMPLETED if anchoring happened earlier (unlikely)
Section: "Anchoring Proof"
- Document hash (SHA-256 or Keccak-256)
- Algorand transaction ID + block explorer link
- BNB Chain transaction ID + block explorer link
- "Anchored on Algorand" (NOT "Approved by Algorand")
- "Anchored on BNB Chain" (NOT "Validated by BNB Chain")
- "View Anchoring Proof" (link to block explorer)
- "Blockchain Action Processing"
- "Smart Contract Validation"
- "Blockchain Approval Status"
6.2 Anchoring Status (if not yet complete)
If plot is REGISTERED but anchoring is pending:
- "Anchoring: Pending"
- "Settlement in progress"
- Block access to registered plot
- Imply that registration is incomplete
- Show anchoring as a blocker
7. Error and Edge Case UI Handling
7.1 Missing Cadastral Code
If cadastral code is invalid or not found:
- Show validation error: "Cadastral code not recognized"
- Suggest checking Public Registry
- Block submission until resolved
- Imply that code doesn't exist
- Blame land owner
7.2 Document Upload Failure
If document upload fails:
- Show technical error message
- Allow retry
- Lose previously entered data
- Force full resubmission
7.3 Verification Takes Longer Than Expected
- Continue showing "Under verification"
- Show submission date (not elapsed time)
- Show countdown or deadline
- Suggest escalation without governance permission
8. Copy Compliance Matrix
| Governance Concept | Allowed UI Copy | Prohibited UI Copy |
|-------------------|-----------------|-------------------|
| Submission | "Submitted for verification", "Registration submitted" | "Submitted for approval", "Pending approval" |
| Verification ongoing | "Under verification", "Verification in progress" | "Being validated", "Approval in progress" |
| Verification complete | "Verification completed", "Registered in platform registry" | "Approved", "Ownership confirmed" |
| Correction needed | "Correction required", "Additional information needed" | "Rejected (fixable)", "Minor issues found" |
| Registration success | "Registered", "Available for platform use" | "Approved", "Confirmed", "Validated" |
| Registration decline | "Registration declined", "Not registered" | "Failed", "Rejected permanently" |
| Blockchain anchoring | "Anchoring proof", "Settlement reference" | "Blockchain approval", "Smart contract validation" |
9. Copilot / AI-Assisted UI Implementation Rules
9.1 Code Generation Constraints
When using AI tools (e.g., GitHub Copilot) to generate UI code:
- Reference this spec explicitly in prompts
- Validate generated code against this spec
- Use prohibited wording list as a filter
- Allow AI to invent states or transitions
- Allow AI to generate copy not in this spec
- Bypass governance constraints for convenience
9.2 Review Checklist
Before deploying any UI change related to EX-PL-01:
- [ ] All status labels match allowed terminology
- [ ] No prohibited wording is present
- [ ] Blockchain references use "Anchoring" / "Settlement" only
- [ ] Verifier identity is hidden from LAND_OWNER
- [ ] Progress indicators are absent (or governance-approved)
- [ ] Legal disclaimers are present where required
- [ ] State-based visibility rules are enforced
10. Explicit Exclusions
This document does NOT define:
- React/Vue/HTML component structure
- CSS styling, layout, or visual design
- Backend API contracts or endpoints
- Database schemas or queries
- State machine implementation logic
- Blockchain smart contract code
This document defines ONLY:
- How governance states map to UI labels
- What information is visible per state and role
- What terminology is allowed or prohibited
- Compliance requirements for UI rendering
11. UNDEFINED / Open Implementation Questions
The following questions MUST be resolved before final UI implementation:
11.1 Visual Design
- UNDEFINED: Color scheme for state badges
- UNDEFINED: Icon set for states and actions
- UNDEFINED: Layout structure (cards, lists, tables)
11.2 Interaction Patterns
- UNDEFINED: Whether modal dialogs or inline forms are used
- UNDEFINED: Whether multi-step forms are allowed (must preserve state visibility)
11.3 Responsive Behavior
- UNDEFINED: Mobile vs desktop experience differences
- UNDEFINED: Whether state transitions trigger notifications
11.4 Accessibility (WCAG)
- UNDEFINED: WCAG compliance level target (A, AA, AAA)
- UNDEFINED: Screen reader-specific state announcements
11.5 Localization
- UNDEFINED: Whether Georgian translations are required
- UNDEFINED: How governance-safe wording is maintained across languages
12. Implementation Validation Requirement
Any UI implementation MUST:
- Be validated against this spec
- Be validated against EX-PL-01-GOVERNANCE-WALKTHROUGH.md
- Be reviewed for compliance with:
- ISO 17020 independence constraints
- ISO 27001 confidentiality constraints
- GDPR visibility rules
- Be auditable (copy and visibility rules traceable)
Validation Checklist Location:
- UNDEFINED — requires governance or QA team input
13. Governance State Legend (UI Reference)
For UI developer reference, the governance states are:
| State Key | Human Label | Land Owner Actions | Verifier Actions | Terminal |
|-----------|-------------|-------------------|------------------|----------|
| DRAFT | Draft | Edit, Delete, Submit | None | No |
| SUBMITTED | Submitted | View only | Assign, Begin verification | No |
| UNDER_VERIFICATION | Under verification | View status | Fill forms, Decide | No |
| VERIFICATION_COMPLETED | Verification completed | View outcome | None (read-only) | No (routing state) |
| CORRECTION_REQUIRED | Correction required | Edit, Resubmit | None (awaiting resubmission) | No |
| REGISTERED | Registered | View, Use in procedures | None (read-only) | Yes |
| DECLINED | Registration declined | View reason, Contact support | None (read-only) | Yes |
| CANCELLED | Cancelled | None | None | Yes |
- UI MAY use
State Key as internal enum/constant
- UI MUST display
Human Label to users
- UI MUST apply action availability per state
14. Action Button Specification
14.1 Button Visibility Matrix
| Button Label | Visible in States | Hidden in States | Enabled Role |
|--------------|------------------|------------------|--------------|
| "Save Draft" | DRAFT | All others | LAND_OWNER |
| "Delete Draft" | DRAFT | All others | LAND_OWNER |
| "Submit for Verification" | DRAFT | All others | LAND_OWNER |
| "Edit" | CORRECTION_REQUIRED | All others | LAND_OWNER |
| "Resubmit" | CORRECTION_REQUIRED | All others | LAND_OWNER |
| "View Anchoring Proof" | REGISTERED | All others | LAND_OWNER, VERIFIER, ADMIN |
| "Use in Inspection" | REGISTERED | All others | LAND_OWNER |
| "Contact Support" | DECLINED | All others (optional in others) | LAND_OWNER |
- MUST NOT use: "Approve", "Confirm"
- MUST use neutral action verbs: "Submit", "Resubmit", "View", "Use"
15. Information Panel Specification
15.1 Land Plot Information Panel (All States)
- Plot reference ID
- Cadastral code
- Current state badge
State-dependent visibility:
- Registry record number (if submitted)
- Registry date (if submitted)
- Submission timestamp (if submitted or later)
Always hidden from LAND_OWNER:
- Verifier identity
- Internal notes or flags
- Decision reasoning (unless formal decline notice)
15.2 Anchoring Proof Panel (REGISTERED only)
- Section heading: "Anchoring Proof"
- Document hash (SHA-256 or Keccak-256)
- Algorand transaction reference + block explorer link
- BNB Chain transaction reference + block explorer link
- "Anchored on Algorand"
- "Anchored on BNB Chain"
- "View on Block Explorer"
- "Blockchain Approval"
- "Smart Contract Validation"
- "Action completed on chain"
- Show: "Anchoring: Pending"
- MUST NOT block access to plot
16. Messaging & Notification Specification
16.1 State Change Notifications
If UI supports notifications:
- "Your land plot registration status has changed to: [STATE]"
- "Verification completed for land plot [ID]"
- "Your land plot was approved!"
- "Congratulations! Ownership verified."
- "Blockchain action completed"
Neutral tone MUST be preserved.
16.2 Error Messages
- "Unable to submit registration. Please try again or contact support."
If verification system is unavailable:
- "Verification system temporarily unavailable. Your submission is preserved and will be processed."
- Blame land owner
- Imply data loss
- Promise specific resolution time
17. GDPR & Data Privacy UI Requirements
17.1 Personal Data Display
Land owner personal data:
- MUST be visible only to:
- Land owner themselves
- Assigned VERIFIER (during verification)
- GOVERNANCE_MANAGER (audit purposes)
- MUST NOT be visible to:
- Other land owners
- Unassigned verifiers
- Public users (unless organizational policy permits)
17.2 Data Subject Rights (UI Support)
UI SHOULD provide mechanisms for:
- LAND_OWNER to view their own data
- LAND_OWNER to request correction (in DRAFT or CORRECTION_REQUIRED states)
- Allow deletion of submitted data (audit trail immutability)
- Allow modification of REGISTERED or DECLINED plots
- UNDEFINED — whether land owner may view access logs of their data
18. Accessibility & Localization Placeholders
18.1 Accessibility (WCAG)
- State changes MUST be announced to screen readers
- Action buttons MUST have ARIA labels
- Status badges MUST have semantic meaning (not color-only)
- UNDEFINED — requires accessibility audit
18.2 Localization
If Georgian language support is required:
Governance-safe translations MUST:
- Preserve neutral, non-promissory tone
- Avoid legal terminology that implies authority
- Maintain consistency with allowed English wording
- UNDEFINED — requires bilingual governance reviewer
19. Implementation Checklist
Before deploying UI changes:
- [ ] All state labels match this spec
- [ ] No prohibited wording is present in any UI string
- [ ] Action buttons are state-gated correctly
- [ ] Verifier identity is hidden from LAND_OWNER
- [ ] Blockchain references use "Anchoring" / "Settlement" only
- [ ] Legal disclaimers are present (if required)
- [ ] Role-based visibility is enforced
- [ ] No progress bars or timelines are shown (unless governance-approved)
- [ ] Error messages are neutral and non-attributional
20. Document Status & Authority
Status: DRAFT — NON-AUTHORITATIVE INPUT
Governance Ratification Required: YES
Implementation Binding: NO (until ratified)
This document is subject to validation by:
- Organizational governance authority
- Legal compliance team
- ISO 17020 / 27001 / 9001 internal auditor
Until ratified, this document serves as:
- Draft guidance for UI implementation
- Non-binding design input
- Subject to revision or rejection
21. Change Control
If governance states, roles, or constraints change:
- EX-PL-01-GOVERNANCE-WALKTHROUGH.md MUST be updated first
- This UI-TRANSLATION-SPEC MUST be updated to reflect walkthrough changes
- UI implementations MUST be re-validated
- Non-compliant UI elements MUST be disabled or removed
Precedence:
Governance > UI Spec > UI Implementation