k-template/README.md

k-template

A production-ready, modular Rust template for K-Suite applications, following Hexagonal Architecture principles.

🌟 Features

• Hexagonal Architecture: Clear separation of concerns between Domain, Infrastructure, and API layers.
• Modular & Swappable: Vendor implementations (databases, message brokers) are behind feature flags and trait objects.
• Feature-Gated Dependencies: Compile only what you need. Unused dependencies are not included in the build.
• Cargo Generate Ready: Pre-configured for cargo-generate to easily scaffold new services.
• Testable: Domain logic is pure and easily testable; Infrastructure is tested with integration tests.

🏗️ Project Structure

The workspace consists of three main crates:

• template-domain: The core business logic.

  • Contains Entities, Value Objects, Repository Interfaces (Ports), and Services.
  • Dependencies: Pure Rust only (no I/O, no heavy frameworks).

• template-infra: The adapters layer.

  • Implements the Repository interfaces defined in template-domain.
  • Content is heavily feature-gated (e.g., sqlite, postgres, broker-nats).

• template-api: The application entry point (Driving Adapter).

  • Wires everything together using dependency injection.
  • Handles HTTP/REST/gRPC interfaces.

🚀 Getting Started

Prerequisites

• Rust (latest stable)
• cargo-generate (cargo install cargo-generate)

Creating a New Project

Use cargo-generate to scaffold a new project from this template:

cargo generate --git https://github.com/your-org/k-template.git

You will be prompted for:

1. Project Name: The name of your new service.
2. Database: Choose between sqlite (default) or postgres.

The template will automatically clean up unused repository implementations based on your choice.

Running Tests

# Run all tests
cargo test

# Run tests for a specific feature (e.g., postgres)
cargo test -p template-infra --no-default-features --features postgres

⚙️ Configuration & Feature Flags

This template uses Cargo features to control compilation of infrastructure adapters.

Feature	Description	Crate
sqlite	Enables SQLite repository implementations and dependencies	template-infra, template-api
postgres	Enables PostgreSQL repository implementations and dependencies	template-infra, template-api
broker-nats	Enables NATS messaging support	template-infra
smart-features	Enables AI/Vector DB capabilities (Qdrant, FastEmbed)	template-infra

Switching Databases

To switch from the default SQLite to PostgreSQL in an existing project, update Cargo.toml:

template-api/Cargo.toml:

[features]
default = ["postgres"] 
# ...

template-infra/Cargo.toml:

[features]
default = ["postgres"]
# ...

📐 Architecture Guide

Adding a New Feature

1. Domain: Define the Entity, Value Objects, and Repository Interface in template-domain.
2. Infra: Implement the Repository Interface in template-infra.
   • Important: Wrap your implementation in a feature flag (e.g., #[cfg(feature = "my-feature")]).
3. API: Wire the new service in template-api/src/main.rs or a dedicated module.

Vendor Isolation

All external dependencies (SQLx, NATS, etc.) should stay within template-infra or template-api. The template-domain crate should remain agnostic to specific technologies.