From a779fce7ea94834f7ed28cfc7a0745d4cdba2964 Mon Sep 17 00:00:00 2001
From: Kristofers Solo <dev@kristofers.xyz>
Date: Tue, 11 Feb 2025 10:49:11 +0200
Subject: [PATCH] docs: update readme

---
 README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 141 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 384576c..b1d81b0 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,148 @@
-# Axum Template
+# Axum Askama Template
 
-This repository contains templates for bootstrapping a Rust Web application with Axum.
+This is a Rust-based web application template built with [Axum](https://github.com/tokio-rs/axum) for the web
+framework and [Askama](https://github.com/rinja-rs/askama) for templating. It
+follows a structured architecture inspired by "[Zero to Production in
+Rust](https://www.zero2prod.com/index.html)" to promote maintainability,
+testability, and scalability.
+
+## Features
+
+* **Axum Web Framework:**  A fast and ergonomic web framework for Rust.
+* **Askama Templating:**  A compile-time HTML templating engine for Rust, ensuring type safety and performance.
+* **Structured Architecture:**  A layered architecture with clear separation of concerns, making the codebase easier to understand and maintain.
+* **Configuration Management:**  Uses `config` crate for managing application settings with support for base, local, and production configurations.
+* **Database Integration:**  Uses `sqlx` for asynchronous database interactions with PostgreSQL.
+* **Telemetry:**  Uses `tracing` and `tracing-bunyan-formatter` for structured logging and tracing.
+* **Middleware:**  Includes request logging middleware using `tower-http`.
+* **Dependency Injection:**  Uses Axum's `with_state` for dependency injection, making it easy to provide shared state to route handlers.
+* **Docker Support:**  Includes a `Dockerfile` for easy containerization.
+* **Justfile:**  Includes a `Justfile` for common development tasks.
+* **`cargo-generate` Template:**  Easily generate new projects from this template using `cargo-generate`.
 
 ## Getting Started
 
-1. Install [`cargo-generate`](https://github.com/cargo-generate/cargo-generate#installation)
+### Prerequisites
 
- ```shell
- cargo install cargo-generate
- ```
+* Rust toolchain (stable or nightly)
+* PostgreSQL database
+* Docker (optional, for containerization)
+* Just (optional, for task running)
+* [`cargo-generate`](https://crates.io/crates/cargo-generate) (recommended for generating new projects)
+* [`bunyan`](https://crates.io/crates/bunyan) (optional, for formatting console logs)
 
-2. Create a new app based on this repository:
+### Configuration
 
- ```shell
- cargo generate kristoferssolo/axum-template
- ```
+1. **Database:**
+
+* Create a PostgreSQL database.
+* Update the database connection string in `config/base.toml` (and `local.toml` or `production.toml` as needed).
+
+2. **Environment Variables:**
+
+* Set any required environment variables (e.g., for email sending).
+
+### Creating a New Project
+
+1. **Install `cargo-generate`:**
+
+```bash
+cargo install cargo-generate
+```
+
+2. **Generate a new project:**
+
+```bash
+cargo generate kristoferssolo/axum-template
+```
+
+### Running the Application
+
+1. **Navigate to the new project directory:**
+
+```bash
+cd <project_name>
+```
+
+2. **Initialize the database:**
+
+```bash
+bash scripts/init_db
+```
+
+3. **Run the application:**
+
+```bash
+cargo run
+```
+
+Or, if you have `just` installed:
+
+```bash
+just dev
+```
+
+4. **Access the application:**
+
+Open your browser and navigate to `http://localhost:8000` (or the configured port).
+
+### Running Tests
+
+```bash
+cargo test
+```
+
+## Directory Structure
+
+```bash
+├── Cargo.toml
+├── config/                 # Handles loading and merging configuration files.
+│   ├── base.toml           # Base configuration
+│   ├── local.toml          # Local development overrides
+│   └── production.toml     # Production configuration overrides
+├── Dockerfile
+├── justfile
+├── migrations/             # Database migrations
+├── README.md               # This file
+├── scripts/                # Utility scripts
+│   └── init_db             # Script to initialize the database
+├── src/
+│   ├── config/             # Configuration loading and management
+│   │   ├── database.rs     # Database connection settings
+│   │   ├── environment.rs  # Environment-related settings (e.g., enum for environment type)
+│   │   └── application.rs  # Application-specific settings
+│   ├── domain/             # Defines the core business logic and data structures.
+│   ├── errors/             # Custom error types
+│   ├── lib.rs             
+│   ├── main.rs
+│   ├── middleware/         # Custom Axum middleware
+│   ├── models/             # Defines the database models (entities).
+│   ├── repositories/       # Provides an abstraction layer for data access.
+│   ├── routes/             # Defines the Axum route handlers.
+│   ├── services/           # Implements the business logic of the application.
+│   └── startup.rs          # Application startup and configuration
+├── templates/              # Askama templates
+├── tests/                  # Integration tests
+│   └── api/                # API-specific tests
+│       ├── health_check.rs # Tests for the health check endpoint
+│       └── helpers.rs      # Helper functions for API tests
+```
+
+### Key Components
+
+* **`config`:**  Handles loading and merging configuration files.
+* **`domain`:**  Defines the core business logic and data structures.
+* **`models`:**  Defines the database models (entities).
+* **`repositories`:**  Provides an abstraction layer for data access.
+* **`services`:**  Implements the business logic of the application.
+* **`routes`:**  Defines the Axum route handlers.
+* **`telemetry`:**  Sets up tracing and logging.
+* **`templates`:**  Contains the Askama templates.
+
+## Contributing
+
+Contributions are welcome! Please submit a pull request with your changes.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).