From e27ec30ab1538afc2714f473344649fb3db85dc8 Mon Sep 17 00:00:00 2001 From: defiQUG Date: Fri, 24 Apr 2026 10:56:05 -0700 Subject: [PATCH] docs: add planning and terminology notes --- ...HAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md | 148 ++++++++++++++++++ .../REPO_LOCAL_RECOMMENDATIONS_STATUS.md | 70 +++++++++ .../CLIENT_DIVISION_TERMINOLOGY.md | 147 +++++++++++++++++ 3 files changed, 365 insertions(+) create mode 100644 docs/00-meta/AAVE_CHAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md create mode 100644 docs/00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md create mode 100644 docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md diff --git a/docs/00-meta/AAVE_CHAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md b/docs/00-meta/AAVE_CHAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md new file mode 100644 index 00000000..a1814e56 --- /dev/null +++ b/docs/00-meta/AAVE_CHAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md @@ -0,0 +1,148 @@ +# AAVE Chain 138 and Marionette TsunamiSwap Plan + +**Last Updated:** 2026-04-23 +**Status:** Active planning / operator runbook +**Purpose:** Canonical repo-local reference for the TsunamiSwap DEX footprint in this workspace, including deployment target, current endpoint, and the operator flow to bring the VM online. + +--- + +## Scope + +This document covers the TsunamiSwap deployment target currently reserved in the Proxmox operational template: + +- **VMID:** `5010` +- **Hostname:** `tsunamiswap` +- **IPv4:** `192.168.11.91` +- **Preferred node:** `r630-01` +- **Category:** `defi` +- **Published port in template:** `80` + +Canonical sources: + +- [docs/00-meta/OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) section `5c` +- [docs/02-architecture/DBIS_NODE_ROLE_MATRIX.md](../02-architecture/DBIS_NODE_ROLE_MATRIX.md) +- [docs/04-configuration/ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md) +- [`config/proxmox-operational-template.json`](../../config/proxmox-operational-template.json) +- [`scripts/deployment/tsunamiswap-vm-5010-provision.sh`](../../scripts/deployment/tsunamiswap-vm-5010-provision.sh) + +--- + +## Current URLs + +The canonical public TsunamiSwap URLs are: + +- **Landing page:** `https://tsunamiswap.com` +- **Working application:** `https://app.tsunamiswap.com` + +The VM service target on port `80` remains the backend origin: + +- **Origin / backend target:** `http://192.168.11.91/` + +Important notes: + +- `https://tsunamiswap.com` is the canonical public landing page. +- `https://app.tsunamiswap.com` is the canonical working application URL. +- `http://192.168.11.91/` remains the internal service origin for VM `5010`. +- Both hostnames are currently recorded against VM `5010`; if the landing page and app split onto different upstreams later, update this document and the Proxmox operational template together. + +--- + +## Deployment State + +Current known state in this repo: + +- VM `5010` exists in inventory and architecture docs. +- The helper script [`scripts/deployment/tsunamiswap-vm-5010-provision.sh`](../../scripts/deployment/tsunamiswap-vm-5010-provision.sh) is **inventory only** and explicitly says provisioning is still informational. +- The operator checklist expects follow-up scripts such as `create-tsunamiswap-vm.sh`, `setup-tsunamiswap-vm-5010.sh`, and `deploy-tsunamiswap-to-5010.sh`, but those scripts are **not present in this workspace** today. +- Because of that, TsunamiSwap should currently be treated as **planned / partially documented infrastructure**, not a fully repo-automated deployment. + +--- + +## Operator Flow + +### 1. Check VM inventory status + +```bash +./scripts/deployment/tsunamiswap-vm-5010-provision.sh +``` + +Expected behavior: + +- Confirms whether VMID `5010` exists on the target Proxmox host. +- If missing, prints the intended sizing and placement. + +### 2. Target VM profile + +From the operator checklist, the intended baseline is: + +- `8` vCPU +- `16 GB` RAM +- `~160 GB` disk +- default host `r630-01` +- default IP `192.168.11.91` + +### 3. Planned post-create steps + +The checklist indicates this intended flow: + +```bash +./scripts/create-tsunamiswap-vm.sh --dry-run +./scripts/create-tsunamiswap-vm.sh +./scripts/setup-tsunamiswap-vm-5010.sh --dry-run +./scripts/setup-tsunamiswap-vm-5010.sh +./scripts/deploy-tsunamiswap-to-5010.sh --dry-run +./scripts/deploy-tsunamiswap-to-5010.sh +``` + +Current repo reality: + +- These commands are referenced operationally. +- The underlying scripts are not present in this workspace right now. +- If automation is needed, those scripts should be added in a future pass and then linked back here. + +--- + +## Publish Checklist + +Before calling TsunamiSwap publicly live, complete all of the following: + +1. Confirm VM `5010` exists and serves HTTP on `192.168.11.91:80`. +2. Confirm `tsunamiswap.com` and `app.tsunamiswap.com` are present under VM `5010` `fqdns` in `config/proxmox-operational-template.json`. +3. Add both hostnames to the canonical endpoint inventory docs. +4. Publish the NPMplus proxy mappings: + `tsunamiswap.com` for the landing page and `app.tsunamiswap.com` for the working application, both currently targeting `192.168.11.91:80`. +5. Verify end-to-end routing with the standard E2E verifier. + +Suggested canonical follow-up files to update once a public hostname exists: + +- [docs/04-configuration/ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md) +- [docs/04-configuration/FQDN_EXPECTED_CONTENT.md](../04-configuration/FQDN_EXPECTED_CONTENT.md) +- [docs/03-deployment/OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md) +- [`config/proxmox-operational-template.json`](../../config/proxmox-operational-template.json) + +--- + +## AAVE / Marionette Relationship + +This workspace currently contains the TsunamiSwap infrastructure reservation and operator references, but it does **not** yet contain a fuller in-repo specification for: + +- AAVE-specific market wiring +- Marionette-specific orchestration details +- TsunamiSwap backend architecture +- TsunamiSwap contract inventory +- TsunamiSwap public domain / branding decision + +So this document should be read as the canonical **deployment placeholder + operator reference**, not a complete product architecture spec. + +--- + +## Decision + +The canonical public URLs for TsunamiSwap in this repo are: + +- `https://tsunamiswap.com` +- `https://app.tsunamiswap.com` + +The corresponding internal service origin is: + +- `http://192.168.11.91/` diff --git a/docs/00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md b/docs/00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md new file mode 100644 index 00000000..7f26d126 --- /dev/null +++ b/docs/00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md @@ -0,0 +1,70 @@ +# Repo-Local Recommendations Status + +**Purpose:** Track the recommendations that can be advanced directly in this repo without requiring LAN-only access, private credentials, or third-party approvals. + +**Canonical sources:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md), [ADDITIONAL_RECOMMENDATIONS_TABLE.md](ADDITIONAL_RECOMMENDATIONS_TABLE.md), [RECOMMENDATIONS_AND_SUGGESTIONS.md](../10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md). + +**Interpretation rule:** This page is only for **repo-local execution**. Operator/LAN tasks and external/vendor tasks stay in their own runbooks and checklists. + +--- + +## Recently advanced in this workspace + +| Area | Recommendation thread | Repo-local progress | +|---|---|---| +| Script UX | Progress indicators / execution visibility | `scripts/run-completable-tasks-from-anywhere.sh` and `scripts/verify/run-all-validation.sh` now print start time, per-step timing, and total elapsed time. | +| Metrics collection | Machine-readable run summaries | `scripts/lib/run-summary.sh` now backs optional `--json-out` summaries for the two main no-LAN runners, writing per-step status/timing JSON under `reports/status/` when requested. | +| Wrapper consistency | Shared summary coverage on orchestration entry points | The E2E, Chain 138 next-steps, and LAN operator wrappers now also expose optional `--json-out` summaries using the same shared helper. | +| Monitoring / health checks | Public non-EVM reachability + lane status | Added `scripts/verify/check-non-evm-network-health.sh`, `scripts/verify/build-non-evm-lane-status.py`, and generated outputs under `reports/status/`. | +| Documentation accuracy | Keep docs aligned with current runner behavior | Stale `Step 1/4–4/4` references were refreshed to the current five-step runner behavior. | +| Documentation discoverability | Cross-links from canonical entry points | Added non-EVM health/lane references to `MASTER_INDEX.md`, `NEXT_STEPS_INDEX.md`, and `scripts/verify/README.md`. | + +--- + +## Repo-local recommendation buckets + +### 1. In progress now + +| Recommendation | Status | Current repo state | +|---|---|---| +| Progress indicators in scripts | Completed for canonical high-use wrappers | Main no-LAN runners plus the E2E, Chain 138 orchestration, and LAN operator wrappers now show clear execution progress and timing. | +| Improve troubleshooting and quick-reference discoverability | Advanced | Existing quick-reference and troubleshooting docs are present; index coverage is being improved incrementally instead of creating duplicates. | +| Script header consistency | Partially addressed | New scripts follow the header pattern; older scripts still vary. Use [SCRIPT_HEADER_TEMPLATE.md](../10-best-practices/SCRIPT_HEADER_TEMPLATE.md) when touching them. | +| Documentation accuracy review | Ongoing | Current pass fixed runner-step drift and added new reference links; broader stale-status review remains ongoing. | + +### 2. Ready for more repo-local work + +| Recommendation | Why it is still repo-local | Suggested next move | +|---|---|---| +| Script header/template normalization | Completed for touched canonical wrappers | High-use wrapper scripts edited in this pass now follow the current header/help/argument-validation pattern. | +| Input validation in scripts | Completed for touched canonical wrappers | The main wrapper scripts now reject unknown args and validate `--wave` / `--json-out` input rather than silently accepting drift. | +| Structured logging for scripts | Advanced | Shared timing/summary behavior is centralized in `scripts/lib/run-summary.sh`; deeper log-level normalization outside the canonical wrappers is no longer part of the active repo-local backlog. | +| Developer documentation / standards | Completed for current canonical flows | Canonical docs now reflect current five-step/no-LAN flow, current 61-address on-chain checks, and summary JSON support. | +| Metrics collection for script execution | Completed for canonical wrappers | Main no-LAN, E2E, Chain 138, and LAN operator wrappers now support optional `--json-out` summaries with per-step status/timing. | + +### 3. Not repo-local in this workspace + +| Recommendation | Reason | +|---|---| +| Blockscout verification settlement, Proxmox firewall changes, SSH hardening, validator key permissions | Requires LAN/host access and sometimes secrets. | +| CoinGecko / CMC / Ledger / Trust Wallet / Consensys / Chainlist submissions | Requires external accounts, outreach, or third-party review. | +| Real bridge sends, operator backups, Proxmox VM provisioning | Requires private keys, LAN, or live infrastructure changes. | + +--- + +## Current repo-local completion state + +The currently identified **repo-local** recommendation backlog in the canonical trackers has been advanced to completion for the main wrapper scripts, validation runners, and index docs. What remains is either: + +1. operator/LAN execution, +2. secrets-required live actions, +3. third-party/vendor follow-through, +4. or future maintenance when script behavior changes again. + +--- + +## Pointers + +- For **all** recommendations: [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) +- For **operator / LAN** actions: [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md) +- For **next-step routing**: [NEXT_STEPS_INDEX.md](NEXT_STEPS_INDEX.md) diff --git a/docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md b/docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md new file mode 100644 index 00000000..14a57c17 --- /dev/null +++ b/docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md @@ -0,0 +1,147 @@ +# Client And Division Terminology + +**Last Updated:** 2026-04-22 +**Status:** Canonical terminology baseline for Phoenix, Sankofa, and Gitea alignment +**Related:** [PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md](PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md), [EXPECTED_WEB_CONTENT.md](EXPECTED_WEB_CONTENT.md), [SERVICE_DESCRIPTIONS.md](SERVICE_DESCRIPTIONS.md), [../04-configuration/PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md](../04-configuration/PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md) + +--- + +## Purpose + +Define the canonical vocabulary for the **commercial / governance layer** and keep it distinct from: + +- **technical tenancy** +- **identity provider terminology** +- **network / infrastructure placement terminology** +- **Mifos / Fineract business-model terminology** + +Use these terms consistently in docs, APIs, config, and UI copy unless a client requires a more specific business label. + +--- + +## Canonical mappings + +| Canonical term | Equivalent / current implementation | Use | +|----------------|--------------------------------------|-----| +| **Client** | GitHub **Enterprise**; Azure **billing profile**; current Gitea **Organization** | Top-level commercial / governance account | +| **Division** | Client-specific subdivision | Generic umbrella term below Client | +| **Division type** | `realm`, `nexus`, `department`, `program`, `legal_entity`, `region`, `office`, `workspace`, etc. | Technical normalization of how a client structures divisions | +| **Tenant** | Phoenix / Kubernetes / app isolation unit | Technical tenancy only | +| **Site** | Proxmox / network / physical location | Infrastructure placement only | + +**Rule:** when the repo needs a neutral term, prefer **Client** and **Division**. + +--- + +## Current clients + +These are the canonical Phoenix client records and should be treated as the top governance / commercial layer: + +- `DBIS` +- `ICCC` +- `OMNL` +- `XOM` +- `AR` +- `EI` +- `PANDA` +- `SAID` + +In current Gitea implementation, each of these maps to an **Organization**. +In Phoenix product language, each of these maps to a **Client**. + +--- + +## Division model + +Each client may implement subdivisions differently. Phoenix must remain flexible enough to support: + +- business labels that are client-specific +- multiple subdivision types under one client +- optional mapping from business divisions to technical tenants + +Recommended normalized model: + +```text +Client + Division + Repository / App / Service / Workspace / Environment +``` + +Examples: + +- `AR` + - divisions labeled **Realms** + - divisions labeled **Nexus** +- `OMNL` + - divisions labeled **legal entities** + - divisions labeled **programs** + - divisions labeled **regional offices** +- `DBIS` + - divisions labeled **departments** + - divisions labeled **member institutions** + - divisions labeled **programs** + +--- + +## Reserved words and collision policy + +The following words already carry specific meanings in the repo and should **not** be used as the global neutral replacement for Division. + +| Term | Reserved meaning | Why it is not the generic business term | +|------|------------------|------------------------------------------| +| **Realm** | Keycloak / OIDC identity boundary; also AR-specific business label | Would collide with both identity and AR business language | +| **Tenant** | Technical isolation boundary in Phoenix / Kubernetes / app models | Already used for namespaces, RBAC, and multi-tenant platform semantics | +| **Site** | Physical / infrastructure placement (Proxmox, network, datacenter) | Already means location / topology | +| **Office** | Org-chart / Fineract / institutional office structure | Too domain-specific for use as the global subdivision primitive | +| **Nexus** | Sankofa / Phoenix branding and AR-specific division label | Strong branding meaning; not stable as a generic structural term | + +--- + +## Implementation guidance + +### Docs + +- Use **Client** for the top account layer. +- Use **Division** when discussing subdivisions generically. +- Use the client-native label only when the business context needs it. + - Example: “AR division type: `realm`” + - Example: “Keycloak realm” + +### UI + +- Internal platform/admin UI may display: + - `Client` + - `Division` +- Client-facing UI may replace `Division` with the client’s native label. + - Example: `Realm` + - Example: `Program Office` + - Example: `Legal Entity` + +### API / config + +- Prefer normalized fields such as: + - `clientId` + - `divisionId` + - `divisionType` + - `tenantId` + - `siteId` + +- Avoid overloading: + - `realm` + - `tenant` + - `site` + +unless that exact platform-specific meaning is intended. + +--- + +## Interpretation guide + +When reading older docs in this repo: + +- “organization” in Gitea context usually means **Client** +- “tenant” in Phoenix platform context usually means **technical tenant**, not client +- “realm” in identity docs means **Keycloak realm** +- “site” means **infrastructure location** + +If a document mixes these layers, update it toward this terminology baseline.