1  # Naming Conventions — Frame17711
  2  
  3  Single source of truth for all naming rules. All LLM agents, developers, and CI pipelines reference this file.
  4  
  5  ## Core Rule
  6  
  7  **17711 goes after the FIRST word** in ALL type/component names, across ALL languages.
  8  
  9  - Pattern: `{FirstWord}17711{RestOfName}`
 10  - Examples: `Service17711Identity`, `Token17711Level`, `Button17711`, `Governance17711Contract`
 11  
 12  ## Rust
 13  
 14  - **Types/structs**: `{FirstWord}17711{RestOfName}` — `Tier17711Config`, `Billing17711Event`
 15  - **Crate names**: `org-17711-mesh-{name}` (open source) / `eu-17711-smart-{name}` (commercial)
 16  - **Module paths**: `org_17711_mesh_{name}::module` / `eu_17711_smart::{domain}::{module}`
 17  - **Error types**: `{Domain}17711Error` — `Crypto17711Error`, `Directory17711Error`
 18  - **Constants**: `SCREAMING_SNAKE` with 17711 — `DNS_ROOT_DEFAULT_SELECTOR`, `IDLE_TIMEOUT_SECS`
 19  
 20  ## Solidity
 21  
 22  - **Contracts**: `{Name}17711Contract` — `Governance17711Contract`, `Quota17711Contract`
 23  - **Base contracts**: `Mesh17711ContractBase`
 24  - **Tokens**: `O17711Token`, `Frame17711Token`
 25  - **Registries**: `{Name}17711Registry` — `Deployment17711Registry`, `VersionedRelease17711Registry`
 26  
 27  ## TypeScript / Vue
 28  
 29  - **Components**: `{Name}17711` — `Button17711`, `Modal17711`, `Table17711`
 30  - **Types/interfaces**: `{Name}17711{Rest}` — `Governance17711Action`, `Question17711Vote`
 31  - **DOM attributes**: `data-component="{Name}17711"`, `data-contract="{hash}"`
 32  
 33  ## Service IDs
 34  
 35  - **Format**: `{namespace}/{service-name}` (dot-separated namespace, slash, kebab-case name)
 36  - **Open source**: `org.17711.mesh/{name}` — `org.17711.mesh/radicle-seed`
 37  - **Commercial**: `eu.17711.smart/{name}` — `eu.17711.smart/code-analysis`
 38  
 39  ## CQRS Bus
 40  
 41  - **Commands**: `"{domain}:{action}"` kebab-case — `"dns:create-record"`, `"audit:scan"`
 42  - **Command structs**: `{Domain}{Action}Command` — `DnsCreateRecordCommand`
 43  - **Query structs**: `{Domain}{Action}Query` — `DnsListRecordsQuery`
 44  
 45  ## Plugin Symbols
 46  
 47  - **Export pattern**: `_{domain}17711_{module}_create` → `Box<dyn Trait>`
 48  - **Examples**: `_code17711_analysis_create`, `_compliance17711_audit_create`
 49  
 50  ## DNS Subdomains
 51  
 52  - **Two base zones** — symmetric structure:
 53  
 54  ### mesh.17711.org (open source)
 55  
 56  | Zone | Pattern | Examples |
 57  |---|---|---|
 58  | Sources | `{repo}.sources.oss.mesh.17711.org` | `org.sources.oss.mesh.17711.org`, `templates.sources.oss.mesh.17711.org` |
 59  | Infra | `infra.sources.oss.mesh.17711.org` | Token-gated (founders) |
 60  | Factory | `{service}.factory.mesh.17711.org` | `ci.factory.mesh.17711.org`, `python.factory.mesh.17711.org` |
 61  | O11y | `{tool}.o11y.mesh.17711.org` | `dashboards.o11y.mesh.17711.org`, `metrics.o11y.mesh.17711.org`, `logs.o11y.mesh.17711.org` |
 62  | O11y alias | `o11y.mesh.17711.org` | → redirects to `dashboards.o11y.mesh.17711.org` |
 63  | Nodes | `node-{id}.mesh.17711.org` | `node-tygjh62h.mesh.17711.org` |
 64  | Services | `{service}.mesh.17711.org` | `api.mesh.17711.org`, `auth.mesh.17711.org`, `catalog.mesh.17711.org`, `impact.mesh.17711.org` |
 65  
 66  ### smart.17711.eu (commercial)
 67  
 68  | Zone | Pattern | Examples |
 69  |---|---|---|
 70  | Sources | `sources.smart.17711.eu` | Token-gated (founders) |
 71  | Infra | `infra.sources.smart.17711.eu` | Token-gated (founders) |
 72  | Factory | `{service}.factory.smart.17711.eu` | `ci.factory.smart.17711.eu` |
 73  | O11y | `{tool}.o11y.smart.17711.eu` | `dashboards.o11y.smart.17711.eu` |
 74  | Nodes | `node-{id}.smart.17711.eu` | Commercial node fleet |
 75  | Services | `{service}.smart.17711.eu` | `api.smart.17711.eu`, `code-analysis.smart.17711.eu` |
 76  
 77  ### Numeronym Abbreviations
 78  
 79  | Short | Full | Pattern | Usage |
 80  |---|---|---|---|
 81  | `o11y` | observability | o + 11 + y | `*.o11y.mesh.17711.org` |
 82  | `i18n` | internationalization | i + 18 + n | `locales/`, Fluent .ftl files |
 83  | `l10n` | localization | l + 10 + n | Region-specific adaptations |
 84  | `a11y` | accessibility | a + 11 + y | WCAG compliance, dApps |
 85  | `c14n` | canonicalization | c + 14 + n | JSON canonical form for BLAKE3 |
 86  | `oss` | open source software | — | `*.oss.mesh.17711.org` |
 87  
 88  ## Radicle Repositories
 89  
 90  | Repo | DNS | Access |
 91  |---|---|---|
 92  ### mesh.17711.org repos
 93  
 94  | Repo | DNS | Access |
 95  |---|---|---|
 96  | `rad:org-17711-mesh` | `org.sources.oss.mesh.17711.org` | Wallet-auth (any wallet) |
 97  | `rad:org-17711-mesh-docs` | `docs.sources.oss.mesh.17711.org` | Wallet-auth (any wallet) |
 98  | `rad:org-17711-mesh-templates` | `templates.sources.oss.mesh.17711.org` | Wallet-auth (any wallet) |
 99  | `rad:org-17711-mesh-sites` | `sites.sources.oss.mesh.17711.org` | Wallet-auth (any wallet) |
100  | `rad:org-17711-mesh-infra` | `infra.sources.oss.mesh.17711.org` | Token-gated (founders) |
101  
102  ### smart.17711.eu repos
103  
104  | Repo | DNS | Access |
105  |---|---|---|
106  | `rad:eu-17711-smart` | `sources.smart.17711.eu` | Token-gated (founders) |
107  | `rad:eu-17711-smart-infra` | `infra.sources.smart.17711.eu` | Token-gated (founders) |
108  
109  ## Repository Directory Structure
110  
111  All repos follow the same symmetric layout (only relevant dirs present):
112  
113  ```
114  {repo}/
115    libs/          # Shared Rust crates
116    bin/           # CLI executables
117    apps/          # Server backends (Axum)
118    dapps/         # Web3 frontends (Vue)
119    services/      # Managed microservices
120    plugins/       # Dynamic .so plugins (libloading)
121    contracts/     # Solidity smart contracts
122    config/        # YAML configs (JSON Schema validated)
123    locales/       # i18n Fluent files (.ftl)
124    docs/          # Documentation
125  ```
126  
127  ## Ansible
128  
129  - **Roles**: hierarchical `org-17711-mesh-{category}-{function}` — functional names, no vendor names:
130    - Factory: `org-17711-mesh-factory-ci-server`, `org-17711-mesh-factory-sources-scm`, `org-17711-mesh-factory-registry-{rust|java|js|python|containers}`
131    - Observability: `org-17711-mesh-o11y-dashboards`, `org-17711-mesh-o11y-metrics`, `org-17711-mesh-o11y-logs`, `org-17711-mesh-o11y-node-metrics`
132    - Gateway: `org-17711-mesh-gateway-reverse-proxy`
133    - Node: `org-17711-mesh-node`, `org-17711-mesh-node-fail2ban`, `org-17711-mesh-node-quadlet`
134    - Services: `org-17711-mesh-service-payment`, `org-17711-mesh-service-inference`, `org-17711-mesh-service-database`, `org-17711-mesh-service-storage-gateway`, `org-17711-mesh-service-operations`
135    - DNS: `org-17711-mesh-dns-authoritative`
136    - dApps: `org-17711-mesh-dapp-auth`
137    - Sites: `{namespace}-{site}` — e.g., `fr-revoirlamer` (not `org-17711-mesh-*`, sites have their own namespace)
138  - **Generic roles** (not mesh-specific): `podman`, `log2ram`
139  - **Playbooks**: `deploy-{service}.yml`
140  - **Quadlet services**: `org-17711-mesh-{category}-{service}.container`
141  
142  ## AWS Resources (commercial — eu.17711.smart)
143  
144  AWS provisioning is **commercial** code in `eu-17711-smart`, not open source.
145  
146  - **Pattern**: `org-17711-mesh-cloud-usa__aws__{function}`
147  - **VPC**: `org-17711-mesh-cloud-usa__aws__vpc`
148  - **Subnets**: `...__subnet-public`, `...__subnet-private`
149  - **Security groups**: `...__sg-mesh`
150  - **Tags** (mandatory): `env`, `branch`, `project`, `country`, `hosting`, `provider`, `service`
151  
152  ## Two Domains — Symmetric Architecture
153  
154  | | `mesh.17711.org` (open source) | `smart.17711.eu` (commercial) |
155  |---|---|---|
156  | **Code** | `org.sources.oss.mesh.17711.org` | `sources.smart.17711.eu` |
157  | **Infra** | `infra.sources.oss.mesh.17711.org` | `infra.sources.smart.17711.eu` |
158  | **Factory** | `*.factory.mesh.17711.org` | `*.factory.smart.17711.eu` |
159  | **O11y** | `*.o11y.mesh.17711.org` | `*.o11y.smart.17711.eu` |
160  | **Nodes** | `node-*.mesh.17711.org` | `node-*.smart.17711.eu` |
161  | **API** | `api.mesh.17711.org` | `api.smart.17711.eu` |
162  | **License** | MIT | Proprietary |
163  | **Access** | Wallet-auth (any wallet) | Token-gated (eu.17711.smart) |
164  | **Revenue** | Treasury17711Split (foundation) | eu.17711.smart commercial |
165  
166  ## Infrastructure Split
167  
168  - **org-17711-mesh-infra** (token-gated founders): HOW to deploy — Ansible roles for services (Radicle, Woodpecker, Caddy, o11y, etc.), Quadlet templates, nftables
169  - **eu-17711-smart** (commercial): WHERE to deploy — AWS/GCP/OVH provisioning, EC2, VPC, SG, AMI, cloud billing, multi-cloud abstraction
170  
171  ## Build ID Convention
172  
173  Format: `v{semver}+{pipeline}.{commit7}` — e.g. `v0.2.2+42.a3f7b21`
174  
175  - `v0.2.2` — workspace semver from `Cargo.toml`
176  - `+42` — Woodpecker pipeline number (auto-incremented)
177  - `.a3f7b21` — first 7 chars of git commit SHA
178  
179  **Every version bump requires founder token wallet signature** — no automated bumps without founder approval.
180  - **Pre-1.0.0** (dev period): single founder signature sufficient
181  - **Post-1.0.0** (production): quorum required (F(5)-of-F(6) = 5-of-8 founders via SIWE)
182  
183  Appears automatically in:
184  - Binary `--version` output (injected by `build.rs`)
185  - Directory `ServiceEntry.version`
186  - Hyperledger Fabric deployment record
187  - Polygon `CiReport17711Contract` + `VersionedRelease17711Registry`
188  - Health endpoint `GET /health` response
189  - `mesh service info {id}` CLI output
190  
191  ## Fibonacci Port Convention
192  
193  - Base: `17711` (F(22))
194  - Bloc 1 (+0): Core P2P — 17711-17713
195  - Bloc 2 (+F(11)=89): DNS — 17800-17809
196  - Bloc 3 (+F(12)=144): Gateway — 17855-17869
197  - Bloc 4 (+F(13)=233): Observability — 17944-17959
198  - Bloc 5 (+F(14)=377): Storage — 18088-18099
199  - Bloc 6 (+F(15)=610): Services — 18321+
200  
201  ## README Format
202  
203  Every module has a `README.md` — bullet points only, no prose:
204  
205  - **What**: one-line description
206  - **Get Started**: clone, build, run, test (concrete commands)
207  - **Build & Version**: version bump, release build
208  - **Config**: env vars, YAML, ports
209  - **Deploy**: Ansible role/playbook reference (if applicable)