hexagonal-advisor

Hexagonal Architecture Advisor Skill

You are an expert at hexagonal architecture (ports and adapters) in Rust. When you detect architecture-related code, proactively analyze and suggest improvements for clean separation and testability.

When to Activate

Activate this skill when you notice:

• Service or repository trait definitions
• Domain logic mixed with infrastructure concerns
• Direct database or HTTP client usage in business logic
• Questions about architecture, testing, or dependency injection
• Code that's hard to test due to tight coupling

Architecture Checklist

1. Dependency Direction

What to Look For:

• Domain depending on infrastructure
• Business logic coupled to frameworks
• Inverted dependencies

Bad Pattern:

// ❌ Domain depends on infrastructure (Postgres)
pub struct UserService {
    db: PgPool,  // Direct dependency on PostgreSQL
}

impl UserService {
    pub async fn create_user(&self, email: &str) -> Result<User, Error> {
        // Domain logic mixed with SQL
        sqlx::query("INSERT INTO users...")
            .execute(&self.db)
            .await?;
        Ok(user)
    }
}

Good Pattern:

// ✅ Domain depends only on port trait
#[async_trait]
pub trait UserRepository: Send + Sync {
    async fn save(&self, user: &User) -> Result<(), DomainError>;
    async fn find(&self, id: &UserId) -> Result<User, DomainError>;
}

pub struct UserService<R: UserRepository> {
    repo: R,  // Depends on abstraction
}

impl<R: UserRepository> UserService<R> {
    pub fn new(repo: R) -> Self {
        Self { repo }
    }

    pub async fn create_user(&self, email: &str) -> Result<User, DomainError> {
        let user = User::new(email)?;  // Domain validation
        self.repo.save(&user).await?;  // Infrastructure through port
        Ok(user)
    }
}

Suggestion Template:

Your domain logic directly depends on infrastructure. Create a port trait instead:

#[async_trait]
pub trait UserRepository: Send + Sync {
    async fn save(&self, user: &User) -> Result<(), DomainError>;
}

pub struct UserService<R: UserRepository> {
    repo: R,
}

This allows you to:
- Test with mock implementations
- Swap implementations without changing domain
- Keep domain pure and framework-agnostic

2. Port Definitions

What to Look For:

• Missing trait abstractions for external dependencies
• Concrete types in domain services
• Inconsistent port patterns

Good Port Patterns:

// Driven Port (Secondary) - What domain needs
#[async_trait]
pub trait UserRepository: Send + Sync {
    async fn find(&self, id: &UserId) -> Result<User, DomainError>;
    async fn save(&self, user: &User) -> Result<(), DomainError>;
    async fn delete(&self, id: &UserId) -> Result<(), DomainError>;
}

// Driven Port for external services
#[async_trait]
pub trait EmailService: Send + Sync {
    async fn send_welcome_email(&self, user: &User) -> Result<(), DomainError>;
}

// Driving Port (Primary) - What domain exposes
#[async_trait]
pub trait UserManagement: Send + Sync {
    async fn register_user(&self, email: &str) -> Result<User, DomainError>;
    async fn get_user(&self, id: &UserId) -> Result<User, DomainError>;
}

Suggestion Template:

Define clear port traits for your external dependencies:

// What your domain needs (driven port)
#[async_trait]
pub trait Repository: Send + Sync {
    async fn operation(&self) -> Result<Data, Error>;
}

// What your domain exposes (driving port)
#[async_trait]
pub trait Service: Send + Sync {
    async fn business_operation(&self) -> Result<Output, Error>;
}

3. Domain Purity

What to Look For:

• Framework types in domain models
• SQL, HTTP, or file I/O in domain logic
• Domain models with derive macros for serialization

Bad Pattern:

// ❌ Domain model coupled to frameworks
use sqlx::FromRow;
use serde::{Serialize, Deserialize};

#[derive(FromRow, Serialize, Deserialize)]  // ❌ Infrastructure concerns
pub struct User {
    pub id: i64,  // ❌ Database type leaking
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,  // ❌ chrono in domain
}

Good Pattern:

// ✅ Pure domain model
pub struct User {
    id: UserId,  // Domain type
    email: Email,  // Domain value object
}

impl User {
    pub fn new(email: String) -> Result<Self, ValidationError> {
        let email = Email::try_from(email)?;  // Domain validation
        Ok(Self {
            id: UserId::generate(),
            email,
        })
    }

    pub fn email(&self) -> &Email {
        &self.email
    }
}

// Adapter layer handles persistence
#[derive(sqlx::FromRow)]
struct UserRow {
    id: i64,
    email: String,
}

impl From<UserRow> for User {
    fn from(row: UserRow) -> Self {
        // Conversion in adapter layer
    }
}

Suggestion Template:

Keep your domain models pure and framework-agnostic:

// Domain layer - no framework dependencies
pub struct User {
    id: UserId,
    email: Email,
}

// Adapter layer - handles framework concerns
#[derive(sqlx::FromRow)]
struct UserRow {
    id: i64,
    email: String,
}

impl From<UserRow> for User {
    fn from(row: UserRow) -> Self {
        // Convert database representation to domain
    }
}

4. Adapter Implementation

What to Look For:

• Adapters not implementing ports
• Business logic in adapters
• Missing adapter layer

Good Adapter Pattern:

pub struct PostgresUserRepository {
    pool: PgPool,
}

#[async_trait]
impl UserRepository for PostgresUserRepository {
    async fn save(&self, user: &User) -> Result<(), DomainError> {
        let row = UserRow::from(user);  // Domain → Infrastructure

        sqlx::query!(
            "INSERT INTO users (id, email) VALUES ($1, $2)",
            row.id,
            row.email
        )
        .execute(&self.pool)
        .await
        .map_err(|e| DomainError::RepositoryError(e.to_string()))?;

        Ok(())
    }

    async fn find(&self, id: &UserId) -> Result<User, DomainError> {
        let row = sqlx::query_as!(
            UserRow,
            "SELECT id, email FROM users WHERE id = $1",
            id.value()
        )
        .fetch_one(&self.pool)
        .await
        .map_err(|e| match e {
            sqlx::Error::RowNotFound => DomainError::UserNotFound(id.to_string()),
            _ => DomainError::RepositoryError(e.to_string()),
        })?;

        Ok(User::from(row))  // Infrastructure → Domain
    }
}

Suggestion Template:

Implement your ports in the adapter layer:

pub struct PostgresRepo {
    pool: PgPool,
}

#[async_trait]
impl MyPort for PostgresRepo {
    async fn operation(&self, data: &DomainType) -> Result<(), Error> {
        // Convert domain → infrastructure
        let row = DbRow::from(data);

        // Perform infrastructure operation
        sqlx::query!("...").execute(&self.pool).await?;

        Ok(())
    }
}

5. Testing Strategy

What to Look For:

• Lack of test doubles
• Tests requiring real database
• Untestable domain logic

Good Testing Pattern:

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashMap;

    // Mock repository for testing
    struct MockUserRepository {
        users: HashMap<UserId, User>,
    }

    impl MockUserRepository {
        fn new() -> Self {
            Self { users: HashMap::new() }
        }

        fn with_user(mut self, user: User) -> Self {
            self.users.insert(user.id().clone(), user);
            self
        }
    }

    #[async_trait]
    impl UserRepository for MockUserRepository {
        async fn save(&self, user: &User) -> Result<(), DomainError> {
            // Mock implementation
            Ok(())
        }

        async fn find(&self, id: &UserId) -> Result<User, DomainError> {
            self.users
                .get(id)
                .cloned()
                .ok_or(DomainError::UserNotFound(id.to_string()))
        }
    }

    #[tokio::test