docs: add planning and terminology notes
This commit is contained in:
defiQUG
148
docs/00-meta/AAVE_CHAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md
Normal file
148
docs/00-meta/AAVE_CHAIN138_AND_MARIONETTE_TSUNAMISWAP_PLAN.md
Normal file
@@ -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/`
|
||||
70
docs/00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md
Normal file
70
docs/00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md
Normal file
@@ -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)
|
||||
147
docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md
Normal file
147
docs/02-architecture/CLIENT_DIVISION_TERMINOLOGY.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user