Infrastructure Naming Discipline Across Architecture Layers

Infrastructure Naming Discipline Across Architecture Layers

Problem

Clean Architecture enforces compile-time layer boundaries via separate crates, but naming conventions can still create conceptual coupling to specific vendors.

Examples found

Framework layer (state.rs):

// Leaky — exposes vendor name
pub supabase_client: SupabaseClient,
pub auth_repo: Arc<SupabaseAuthRepository>,  // concrete type, not trait

// Clean — provider-agnostic
pub cloud_client: CloudClient,
pub auth_repo: Arc<dyn AuthRepository>,      // trait object

Tauri commands:

// Leaky — vendor in command name
#[tauri::command]
fn supabase_health_check() -> Result<(), String> { ... }

// Clean
#[tauri::command]
fn cloud_health_check() -> Result<(), String> { ... }

Rule

Layer	Vendor names	Example
Infrastructure	Expected and correct	SupabaseAuthRepository, SupabaseSyncRepository
Application	Never — traits only	AuthRepository, SyncRepository
Framework	Avoid — use provider-agnostic names	cloud_client, auth_repo: Arc<dyn AuthRepository>
Frontend	Acceptable only for transport adapters	supabase.ts if it’s purely a Realtime transport

Why This Matters

1. Swappability: If you ever move from Supabase to another backend, framework-layer code shouldn’t change
2. Mental model: Developers should think in terms of “cloud sync” and “auth”, not “Supabase”
3. Consistency: The architecture already enforces this at compile time for domain/application layers — naming should follow

Inherent methods vs trait methods

A specific form of this leak: methods that should be on a trait but are instead inherent methods on a concrete type.

// Leaky — only available on the concrete type
impl SupabaseAuthRepository {
    pub fn ensure_valid_token(&self) -> AuthResult<String> { ... }
}

// Clean — available through the trait
trait AuthRepository {
    fn ensure_valid_token(&self) -> AuthResult<String>;
}

Any code calling ensure_valid_token() must import the concrete type, breaking the abstraction.

References

• Linear: INK-157 (naming audit), INK-154 (auth trait refactor)