architecture

name: architecture description: Guides the design of safely disposable code through contracts (traits/interfaces) and dependency inversion. Use when designing new modules, refactoring existing code, or making architectural decisions about component boundaries.

Safely Disposable Code via Contracts

Every implementation should be disposable. The system's correctness is defined by its contracts, not by any particular implementation behind them.

Core Principle

Define what a component does (contract), not how it does it (implementation). Any implementation that satisfies the contract is interchangeable.

A component is "safely disposable" when:

1. Its behavior is fully described by a contract (trait, interface, protocol)
2. No consumer depends on implementation details
3. It can be deleted and rewritten from the contract alone without breaking the system

Workflow

Step 1: Define the Contract

Start with the contract. Write the trait/interface before any implementation.

Rust:

pub trait UserRepository {
    fn find_by_id(&self, id: UserId) -> Result<Option<User>, RepoError>;
    fn save(&self, user: &User) -> Result<(), RepoError>;
}

Go:

type UserRepository interface {
    FindByID(ctx context.Context, id UserID) (*User, error)
    Save(ctx context.Context, user *User) error
}

TypeScript:

interface UserRepository {
  findById(id: UserId): Promise<User | null>;
  save(user: User): Promise<void>;
}

Rules:

• Keep contracts small (1-5 methods)
• Name contracts after the role, not the implementation (e.g., UserRepository, not PostgresUserStore)
• Define contracts where they are consumed, not where they are implemented
• Use domain types in signatures, not infrastructure types

Step 2: Define Error Contracts

Errors are part of the contract. Define domain-level error types that hide infrastructure details.

#[derive(Debug, thiserror::Error)]
pub enum RepoError {
    #[error("entity not found: {0}")]
    NotFound(String),
    #[error("conflict: {0}")]
    Conflict(String),
    #[error("internal error")]
    Internal(#[source] Box<dyn std::error::Error + Send + Sync>),
}

The Internal variant wraps infrastructure errors without leaking them into the contract.

Step 3: Implement Against the Contract

Each implementation is a disposable artifact. Write it knowing it can be thrown away.

pub struct PgUserRepository {
    pool: PgPool,
}

impl UserRepository for PgUserRepository {
    fn find_by_id(&self, id: UserId) -> Result<Option<User>, RepoError> {
        // Postgres-specific code here.
        // This entire struct is disposable.
    }

    fn save(&self, user: &User) -> Result<(), RepoError> {
        // ...
    }
}

Step 4: Depend on Contracts, Not Implementations

Consumers accept the contract, never the concrete type.

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

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

    pub fn get_user(&self, id: UserId) -> Result<Option<User>, RepoError> {
        self.repo.find_by_id(id)
    }
}

In Go, this is implicit — accept the interface:

func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

Step 5: Test Against the Contract

Write tests that verify the contract, not the implementation. These tests can be reused across implementations.

// A test suite that works for ANY UserRepository implementation.
fn test_repository_contract(repo: &impl UserRepository) {
    let user = User::new("test@example.com");
    repo.save(&user).unwrap();

    let found = repo.find_by_id(user.id()).unwrap();
    assert_eq!(found, Some(user));
}

#[test]
fn pg_repo_satisfies_contract() {
    let repo = PgUserRepository::new(test_pool());
    test_repository_contract(&repo);
}

#[test]
fn in_memory_repo_satisfies_contract() {
    let repo = InMemoryUserRepository::new();
    test_repository_contract(&repo);
}

Layered Architecture

Organize code so that dependencies always point inward toward the domain:

src/
├── domain/          # Contracts + domain types (zero external deps)
│   ├── model.rs     #   Domain entities and value objects
│   ├── repo.rs      #   Repository contracts (traits)
│   └── service.rs   #   Domain services using contracts
├── infra/           # Disposable implementations
│   ├── pg_repo.rs   #   Postgres implementation
│   └── http.rs      #   HTTP handlers
└── main.rs          # Wiring (connects contracts to implementations)

• domain/ defines contracts and types. It imports nothing from infra/.
• infra/ implements contracts. It imports from domain/.
• main.rs wires implementations to contracts.

Disposability Checklist

Before considering a component done, verify:

• A contract (trait/interface) exists and lives in the domain layer
• The contract is named after the role, not the technology
• Errors are domain-level, not infrastructure-level
• Consumers depend on the contract, not the implementation
• The implementation can be deleted without changing any consumer code
• Contract-level tests exist and can run against any implementation
• No implementation details leak through the contract (e.g., SQL types, HTTP types)

Anti-Patterns

When NOT to Abstract

Not everything needs a contract. Skip abstraction when:

• The component is a pure function with no side effects
• There will genuinely never be an alternative implementation
• The "contract" would be a trivial 1:1 mirror of a standard library type
• You're early in exploration and the boundary isn't clear yet

Start concrete, extract a contract when the second use case appears or when you need testability.