Project Templates Guide

Armature provides starter templates to help you quickly bootstrap new projects. Each template is designed for a specific use case and includes best practices.

Table of Contents

• Overview
• Available Templates
• Using Templates
• Template Details
• Customization
• Best Practices

Overview

Templates are located in the templates/ directory:

templates/
├── README.md
├── api-minimal/          # Bare-bones REST API
├── api-full/             # Full-featured API
├── graphql-api/          # GraphQL API server
└── microservice/         # Queue-connected worker

Available Templates

Using Templates

Quick Start

# Copy a template
cp -r templates/api-minimal my-project
cd my-project

# Update project name in Cargo.toml
# Configure .env from .env.example

# Run
cargo run

Template-Specific Setup

api-minimal

cp -r templates/api-minimal my-api
cd my-api
cp .env.example .env
cargo run
# Server at http://localhost:3000

api-full

cp -r templates/api-full my-api
cd my-api
cp .env.example .env
# Edit .env with your JWT_SECRET
cargo run
# Server at http://localhost:3000

For production with Docker:

docker-compose up -d

graphql-api

cp -r templates/graphql-api my-graphql
cd my-graphql
cp .env.example .env
cargo run
# GraphQL Playground at http://localhost:3000/graphql

microservice

cp -r templates/microservice my-worker
cd my-worker
cp .env.example .env
# Configure REDIS_URL
cargo run

Template Details

api-minimal

The simplest starting point for learning Armature.

Features:

• Single main.rs file
• Basic CRUD operations
• Health check endpoint
• In-memory data store

Structure:

api-minimal/
├── Cargo.toml
├── .env.example
└── src/
    └── main.rs

Endpoints:

• GET /health - Health check
• GET /api/users - List users
• GET /api/users/:id - Get user
• POST /api/users - Create user
• DELETE /api/users/:id - Delete user

api-full

Production-ready API with authentication and validation.

Features:

• JWT authentication
• Request validation
• Structured logging
• Docker support
• Health checks (liveness/readiness)
• Error handling

Structure:

api-full/
├── Cargo.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── src/
    ├── main.rs
    ├── config.rs
    ├── models.rs
    ├── middleware.rs
    ├── controllers/
    │   ├── mod.rs
    │   ├── auth.rs
    │   ├── health.rs
    │   └── user.rs
    └── services/
        ├── mod.rs
        ├── auth.rs
        └── user.rs

Endpoints:

• GET /health - Full health check
• GET /health/live - Liveness probe
• GET /health/ready - Readiness probe
• POST /api/auth/login - Login
• POST /api/auth/register - Register
• GET /api/users - List users (authenticated)
• GET /api/users/:id - Get user (authenticated)
• DELETE /api/users/:id - Delete user (authenticated)

graphql-api

Production-ready GraphQL API with queries, mutations, and subscriptions.

Features:

• GraphQL Playground/GraphiQL
• Query and Mutation resolvers
• Subscription support
• Type-safe schema
• Pagination support
• Authentication integration
• Structured logging

Structure:

graphql-api/
├── Cargo.toml
├── .env.example
└── src/
    ├── main.rs
    ├── config.rs
    ├── context.rs
    ├── schema/
    │   ├── mod.rs
    │   ├── query.rs
    │   ├── mutation.rs
    │   ├── subscription.rs
    │   └── types.rs
    └── services/
        ├── mod.rs
        ├── auth.rs
        ├── user.rs
        └── book.rs

Endpoints:

• GET /graphql - GraphQL Playground
• POST /graphql - GraphQL endpoint
• GET /health - Health check
• GET /health/live - Liveness probe
• GET /health/ready - Readiness probe

Example Queries:

# List all users
query {
  users {
    items { id name email role }
    total
    hasMore
  }
}

# Get a specific book with author
query {
  book(id: "1") {
    id
    title
    author { name email }
  }
}

# Create a user
mutation {
  createUser(input: { name: "Alice", email: "alice@example.com" }) {
    id
    name
  }
}

# Search books
query {
  searchBooks(query: "Rust") {
    id
    title
    publishedYear
  }
}

microservice

Background job processor with health monitoring.

Features:

• Job queue processing
• Retry with backoff
• Prometheus metrics
• Graceful shutdown
• Docker support

Structure:

microservice/
├── Cargo.toml
├── Dockerfile
├── .env.example
└── src/
    ├── main.rs
    ├── config.rs
    ├── handlers.rs
    └── jobs.rs

Endpoints:

• GET /health - Service health with job stats
• GET /health/live - Liveness probe
• GET /health/ready - Readiness probe
• GET /metrics - Prometheus metrics

Job Types:

• send_email - Email sending
• send_notification - Push/SMS/Slack notifications
• process_data - Data processing

Customization

Adding a Database

# Cargo.toml
[dependencies]
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres"] }

// src/main.rs
let pool = PgPoolOptions::new()
    .max_connections(5)
    .connect(&env::var("DATABASE_URL")?)
    .await?;

Adding Rate Limiting

# Cargo.toml
[dependencies]
armature-framework = { version = "0.1", features = ["ratelimit"] }

use armature_ratelimit::{RateLimiter, Algorithm};

let limiter = RateLimiter::builder()
    .token_bucket(100, 10.0)
    .build()
    .await?;

Adding Caching

# Cargo.toml
[dependencies]
armature-framework = { version = "0.1", features = ["cache"] }

Adding Validation

# Cargo.toml
[dependencies]
armature-framework = { version = "0.1", features = ["validation"] }

Adding OpenAPI Docs

# Cargo.toml
[dependencies]
armature-framework = { version = "0.1", features = ["openapi"] }

Best Practices

1. Configuration

Always use environment variables for configuration:

let config = AppConfig::from_env();

Never commit secrets to version control. Use .env.example as a template.

2. Logging

Use structured logging with tracing:

use tracing::{info, debug, error};

info!(user_id = %user.id, "User logged in");

3. Error Handling

Return consistent error responses:

#[derive(Serialize)]
struct ApiError {
    code: String,
    message: String,
}

HttpResponse::bad_request().json(ApiError {
    code: "VALIDATION_ERROR".into(),
    message: "Invalid input".into(),
})

4. Health Checks

Always include health endpoints for container orchestration:

• /health - Full health check
• /health/live - Is the process alive?
• /health/ready - Can it accept traffic?

5. Docker Best Practices

Use multi-stage builds:

# Build stage
FROM rust:1.85 AS builder
# ... build ...

# Runtime stage
FROM debian:bookworm-slim
# ... minimal runtime ...

6. Security

• Use strong JWT secrets (32+ random bytes)
• Hash passwords with bcrypt/argon2
• Validate all input
• Use HTTPS in production
• Implement rate limiting

Creating New Templates

To add a new template:

1. Create directory under templates/
2. Include minimum files:
   • Cargo.toml
   • src/main.rs
   • .env.example
3. Follow existing patterns
4. Update templates/README.md
5. Add to this guide

Summary

Templates provide a quick start for common project types:

All templates follow Armature best practices and can be customized as needed.