Console Information Architecture

1. Status

This document defines the target Console menu and route organization for OrbitMesh's long-term product architecture.

The menu is not limited to the current Traffic implementation. Implementation readiness is tracked inside each page. Console navigation should reflect the product model without turning the sidebar into a raw capability inventory.

2. Principles

• Console navigation follows product capabilities, not implementation runtimes.
• Gateway is not the generic name for all installed hosts.
• Traffic Entry and Traffic Exit are Traffic roles, not top-level menus.
• sing-box is shown as a runtime binding, not as the product.
• Certificates are managed as domain and endpoint infrastructure.
• Runtime Catalog administration is a platform capability. Tenant Console may show read-only bindable runtime and install profile information, but platform operator workflows belong in apps/platform, not apps/console.
• Long-term capabilities can be visible before they are fully implemented, but their pages must show clear capability positioning, supported runtimes, current status, and implementation path.

3. Target Console Menu

Use this menu as the target product information architecture:

Workspace
  Overview
  Workspaces

Infrastructure
  Nodes
  Enroll Node
  Endpoints
  Domains & TLS
  Runtime Catalog

Capabilities
  Traffic
  Mesh
  Gateway
  Tunnel

Operations
  Usage & Quotas
  Infrastructure Traffic
  Plan & Billing

Administration
  Workspace Settings
  Team
  Members
  Roles
  Identity Providers

The terminal model still includes Traffic, Mesh, Gateway, and Tunnel, but the sidebar is organized by stable product operating domains:

• Workspace is the current workspace entry point and workspace switcher surface.
• Infrastructure owns hosts, edge runtime enrollment, node endpoints, domains, certificates, and tenant-facing runtime catalog visibility.
• Capabilities owns Traffic, Mesh, Gateway, and Tunnel product workflows.
• Operations owns usage, quota, infrastructure traffic, plan entitlement, and billing state.
• Administration owns workspace settings, team membership, roles, and identity provider integration.

Runtime Platform is part of Infrastructure. Domains and certificates are infrastructure resources. Plan and billing are grouped with Operations because they explain resource consumption, quota, entitlement, and charge boundaries. Team administration is a dedicated Administration domain instead of being mixed into the Workspaces switcher.

Planned capability pages must not be blank placeholders. They must explain capability positioning, runtime candidates, managed resource types, current status, and implementation path.

Global sidebar entries must stay at the product domain level. Capability-specific resources belong in the capability page's secondary navigation:

Traffic
  Overview
  Client Access
  Routing Policies
  Traffic Paths
  Usage & Quotas

The same pattern applies as Mesh, Gateway, and Tunnel expand:

Mesh
  Overview
  Networks
  Peers
  Routes
  Relays

Gateway
  Overview
  Services
  Routes
  TLS
  Load Balancers

Tunnel
  Overview
  Public Endpoints
  Tunnel Services
  Temporary Shares

4. Route Plan

Current route names should be replaced instead of kept as aliases.

During this development phase, route migration can be breaking. Do not add route aliases unless a production release requires them later.

5. Page Responsibilities

5.1 Overview

Shows the tenant-level operating state:

• active nodes.
• online and degraded Edge Runtime count.
• enabled Traffic roles.
• subscription count.
• traffic usage.
• certificate readiness.
• recent control-plane errors.

Overview should summarize capability health, not runtime internals first.

5.2 Nodes

Replaces the old Gateways page.

Primary objects:

• Node identity.
• Edge Runtime status.
• reachability.
• enabled capability bindings.
• runtime bindings.
• runtime versions.
• endpoints on the node.
• last heartbeat.
• last desired state apply result.

Node detail should group data as:

Summary
Capabilities
Runtime Bindings
Endpoints
Certificates
Infrastructure Traffic
Events

Traffic roles should display as:

Traffic Entry
Traffic Exit
Traffic Relay

not as:

Ingress Gateway (legacy)
Egress Gateway (legacy)

5.3 Enroll Node

Replaces the old Install page.

Responsibilities:

• create deployment token.
• choose initial node source type.
• choose initial capability intent.
• render install command.
• show token expiry and one-time use status.

Initial capability intent examples:

• Traffic Entry.
• Traffic Exit.
• Traffic Entry + Exit.
• Mesh Node.
• Tunnel Endpoint.

For the current implementation stage, only Traffic Entry and Traffic Exit need to be active choices.

5.4 Traffic Client Access

Replaces Client Configurations.

Client Access represents:

• client access credential.
• subscription token.
• output formats.
• selected traffic entry endpoints.
• traffic policy scope.
• usage and quota state.

Supported output formats can include:

• Clash.
• Surge.
• Shadowrocket.
• sing-box.
• generic URI list.

The output target list and client profile presets come from /api/v1/subscription-target-catalog. Console renders catalog entries and their profiles; it must not hard-code client variants.

The page should show:

• subscription status.
• copied URL.
• catalog target metadata.
• profile parameters such as version, template, and node_name_strategy.
• rotate token.
• revoke.
• soft-delete revoked subscriptions.
• bound entry endpoints.
• usage and quota.
• last used time.

The backend resource may still be named subscription during the current implementation phase. Product-facing text should prefer Client Access or Client Access Subscription.

5.5 Traffic Policies

Owns Traffic routing policy.

Responsibilities:

• policy scope.
• selectors.
• exit selection.
• priority.
• preview.
• compile impact.

Use Traffic terms:

• Entry.
• Exit.
• Route.
• Policy.

Avoid Gateway terms unless the page is inside the Gateway Capability section.

5.6 Usage & Quotas

Owns client access Traffic usage reporting and enforcement.

Views:

• tenant client access usage.
• user client access usage.
• subscription client access usage.
• entry node client access attribution.
• runtime binding usage.
• direction.
• quota status.
• exceeded events.

Current Console behavior:

• summary cards for billable client access traffic, raw upload, raw download, subscription rows, user rows, node rows, credential blocks, and policy count.
• attribution coverage for user, subscription, and node usage.
• table filtering by scope, concrete target, and direction.
• subscription and node usage rows link back to their owning resource.
• subscription details include applicable quota policies and enforcement state.
• usage rows can open adjustment for an active enforcement or prefill quota policy creation.
• quota events and enforcement rows show whether the policy only alerts or withholds runtime credentials.
• exceeded disable quotas are presented as credential blocking: subscription URLs remain accessible, but affected credentials are excluded from generated runtime configs.

Traffic usage should be attributed to:

• tenant.
• user.
• subscription.
• node.
• capability role.
• runtime binding.
• runtime.
• endpoint where available.

This page is not the primary infrastructure traffic page. It must not combine client_access, exit_egress, and relay_transit into a single billable total.

5.6.1 Infrastructure Traffic

Owns infrastructure traffic reporting.

Views:

• node traffic by metering point.
• Traffic Exit egress usage.
• Traffic Relay forwarding usage.
• Mesh transit usage.
• runtime local control and probe traffic.
• runtime binding traffic.
• endpoint traffic where available.

Metering points:

client_access   entry-side client accounting, shown here only as node attribution
exit_egress     Traffic Exit outbound provider and capacity accounting
relay_transit   Traffic Relay forwarding accounting
mesh_transit    mesh internal transit accounting
runtime_local   runtime management and probe traffic

Primary audience:

• tenant operator.
• platform operator.
• node owner.

This page is read-only for accounting. Quota changes still belong to Usage & Quotas.

5.6.2 Mesh Overview

Mesh is a first-class capability.

Responsibilities:

• private networks.
• peers.
• NAT traversal.
• relay nodes.
• subnet routes.
• node-to-node reachability.

Supported runtime candidates:

• EasyTier.
• Tailscale.
• NetBird.
• WireGuard.
• ZeroTier.

Current implementation can expose an overview page with planned status until mesh networks and route resources are implemented.

5.6.3 Gateway Overview

Gateway is a first-class capability for service ingress and routing.

Responsibilities:

• HTTP service routes.
• TCP service routes.
• TLS termination.
• load balancing.
• domain binding.
• middleware policy.

Supported runtime candidates:

• Traefik.
• NGINX.
• Envoy.
• HAProxy.
• Caddy.

Gateway must not be confused with Traffic Entry. Traffic Entry is a Traffic role; Gateway is a service ingress capability.

5.6.4 Tunnel Overview

Tunnel is a first-class capability for public exposure of private services.

Responsibilities:

• public endpoint allocation.
• tunnel services.
• temporary shares.
• relay paths.
• access policy.

Supported runtime candidates:

• frp.
• Cloudflare Tunnel.
• EasyTier relay.
• ngrok-like runtime.

Tunnel overlaps with Gateway at the endpoint layer, but it solves a different product problem: exposing private services without direct public reachability.

5.7 Endpoints

Endpoints should become a first-class infrastructure resource page.

Responsibilities:

• endpoint address.
• endpoint role.
• protocol.
• port.
• DNS target.
• certificate binding.
• readiness.
• owning node.
• owning capability binding.
• owning runtime binding.

Endpoint examples:

• traffic.entry Trojan endpoint.
• gateway.http HTTPS endpoint.
• tunnel.http public endpoint.
• mesh.node private address.

The current implementation stage can start by showing Traffic Entry endpoints only.

Current implementation:

• Traffic Entry endpoints are shown in Node detail.
• endpoint address, role, purpose, scope, protocol, port, DNS record, TLS binding, certificate status, and expiry are visible with the owning node context.
• endpoint readiness is derived from endpoint status, DNS status, and certificate status.
• endpoint changes are driven by Control Plane desired state and Edge Runtime reload, not by a standalone Endpoint CRUD form.

5.8 Domains & TLS

Replaces the standalone Certificates page.

Responsibilities:

• system domains.
• tenant custom domains.
• DNS status.
• ownership validation.
• ACME status.
• certificate status.
• bound endpoints.
• expiry and renewal state.

Certificates should not appear as isolated resources without their domain and endpoint context.

Current implementation:

• /network/domains is the DNS and TLS readiness dashboard.
• each row represents a domain and TLS binding attached to a Traffic Entry endpoint.
• summary cards show total bindings, ready bindings, endpoint pending, DNS pending, certificate pending, and errors.
• operators can refresh the page, open the owning node, or reload the owning node to reconcile DNS/TLS desired state.
• custom domain onboarding and standalone certificate CRUD are deferred until the base DNS/TLS lifecycle is stable.

5.9 Runtime Catalog

Runtime Catalog belongs under Infrastructure because operators use it while managing nodes, runtime bindings, and install profiles.

Responsibilities:

• runtime metadata.
• supported capabilities.
• supported roles.
• parameter schema.
• install profile.
• plugin status.

This page is useful for operators and developers. It should not dominate the ordinary user workflow.

Runtime Catalog in Tenant Console is read-only tenant-facing visibility. Editing runtime catalog entries, install profiles, plugin status, and subscription target catalog entries is a Platform Console workflow and must live under apps/platform.

5.10 Plan & Billing

Plan & Billing belongs under Billing.

Responsibilities:

• current tenant plan subscription.
• plan status and current billing period.
• enabled capabilities.
• included client access traffic.
• current client access usage.
• node limit and current node count.
• member limit and current member count.
• client access subscription limit and current count.
• runtime binding limit.
• plan-derived quota state.
• manual quota overrides.

Tenant Console must only display the tenant's current plan, usage, limits, and tenant-scoped quota state. Plan catalog creation, plan versioning, pricing, tenant plan assignment, suspension, expiration, and platform resource allowance management are Platform Console responsibilities and must live under apps/platform.

Primary audience:

• tenant owner.
• tenant admin.
• billing role.

The current implementation does not expose payment provider operations. Plan catalog mutation can remain seed-driven or system-admin-only.

5.11 Workspace Settings

Workspace Settings shows the active tenant context, current user, console version, and control-plane version.

Responsibilities:

• active tenant.
• tenant id.
• current user's effective tenant role.
• console version and commit.
• API version and commit.
• API base URL.

This page is operational metadata. It should not become a dumping ground for members, roles, identity providers, or billing.

5.12 Team

Team is the user-facing collaboration and account-management container above tenant resources.

Responsibilities:

• team identity.
• tenant ownership.
• tenant list.
• account boundary.
• future billing account relationship.
• future identity provider ownership.

Current implementation:

• Team shows the active tenant as the user-facing workspace.
• Team name can be updated through PATCH /api/v1/tenants/{id}.
• Workspace Settings and the active Workspaces row link directly to Team Settings so name management remains discoverable.
• A successful rename updates the active Console tenant state immediately without requiring a reload or workspace switch.
• Tenant remains the isolation boundary for nodes, subscriptions, policies, usage, and desired state.
• The page shows current user's tenant role and membership status.

5.13 Members

Members manages tenant membership.

Responsibilities:

• tenant users.
• role per user.
• membership status.
• source of membership.
• invitation status.
• future external group mapping source.

Current implementation uses dedicated tenant member APIs:

• GET /api/v1/tenants/{tenant_id}/members
• POST /api/v1/tenants/{tenant_id}/members
• PATCH /api/v1/tenants/{tenant_id}/members/{id}
• DELETE /api/v1/tenants/{tenant_id}/members/{id}
• GET /api/v1/tenants/{tenant_id}/invitations
• POST /api/v1/tenants/{tenant_id}/invitations
• POST /api/v1/tenants/{tenant_id}/invitations/{id}/revoke
• POST /api/v1/team-invitations/accept

The current implementation supports adding an existing OrbitMesh user by email, changing assignable roles, disabling a member, creating invitation tokens, listing invitation status, and revoking pending invitations. Invitation token is returned only once on creation. Email delivery is not implemented yet.

5.14 Roles

Roles defines tenant RBAC semantics.

Built-in roles:

• owner.
• admin.
• member.
• viewer.
• billing.

Compatibility role:

• operator.

operator is legacy admin-equivalent until migrated. New product flows should prefer admin. Role and permission metadata is served by GET /api/v1/tenant-role-catalog; Console must render role semantics and permission catalog from that API instead of hard-coding a second source of truth.

Custom roles are future enterprise functionality and should map to explicit permissions rather than hard-coded UI conditionals.

5.15 Identity Providers

Identity Providers maps external identity sources into OrbitMesh users, tenant memberships, and roles.

Target providers:

• OIDC.
• GitHub Team.
• Feishu.
• WeCom.

Mapping model:

external user subject -> OrbitMesh user
external group/team -> tenant role

Business pages must consume effective membership and permission. They must not call external identity providers directly.

Current implementation:

• Console manages provider configuration from /settings/identity-providers.
• API supports list, create, update, and soft-disable for tenant identity providers.
• config_json is validated as a JSON object.
• mappings_json is validated as a JSON array.
• Supported provider kinds are oidc, github_team, feishu, and wecom.
• External auth flow, group sync, and automatic user provisioning remain follow-up work.

6. Implementation Status

Current visible subset:

Workspace
Infrastructure
Capabilities
Operations
Administration

Capability child pages that are not implemented yet can remain represented by overview pages:

Mesh
  Overview
  Networks
  Peers
  Routes
  Relays

Gateway
  Overview
  Services
  Routes
  Load Balancers
  TLS

Tunnel
  Overview
  Public Endpoints
  Tunnel Services
  Temporary Shares

Overview pages must include capability positioning, runtime candidates, managed resource types, current status, and implementation path. They must not be blank placeholders.

7. Current Alignment Work

Before new feature development resumes:

1. Rename Console labels from Gateway to Node where the page means host or Edge Runtime.
2. Rename Client Configurations to Client Access.
3. Rename Certificates to Domains & TLS.
4. Group Traffic, Mesh, Gateway, and Tunnel under Capabilities.
5. Show traffic.entry and traffic.exit as roles.
6. Show sing-box only as runtime binding.
7. Add Endpoint context to subscription and certificate views.
8. Move Runtime Catalog under Infrastructure.
9. Expose Traffic, Mesh, Gateway, and Tunnel overview pages as capability entry points.
10. Keep Team, Members, Roles, and Identity Providers under Administration.
11. Keep usage, quota, infrastructure traffic, plan, and billing under Operations.
12. Keep Client Access, Routing Policies, and Traffic Paths inside the Traffic page secondary navigation instead of global sidebar items.