# {{app_name}}
Clean HTTP API service built with Axum and SeaORM (no authentication).
## Architecture
This application follows **Hexagonal Architecture** (Ports & Adapters pattern):
```
src/
├── main.rs # Application entry point
├── config.rs # Configuration loading
├── state.rs # Shared application state
├── error.rs # Error types
├── features/ # Domain features
│ └── health/ # Health check feature
│ ├── mod.rs
│ ├── handler.rs # HTTP handler (inbound adapter)
│ └── service.rs # Business logic
└── adapters.rs # Outbound adapters
└── entities.rs # SeaORM database entities
```
### Layers:
1. **Inbound Adapters** (`handler.rs`): HTTP layer, receives requests
2. **Core/Domain** (`service.rs`): Business logic, pure functions
3. **Outbound Adapters** (`adapters/`): Database, external services
## Features
- ✅ RESTful API with Axum
- ✅ PostgreSQL with SeaORM
- ✅ CORS configuration
- ✅ Request logging and distributed tracing
- ✅ Health check endpoint
- ✅ Structured error handling
- ✅ Clean hexagonal architecture
- ❌ **No authentication** (for internal services or when auth is handled elsewhere)
## Getting Started
### Prerequisites
- Rust 1.91+ (edition 2024)
- PostgreSQL database
### Setup
1. **Copy environment variables**:
```bash
cp .env.example .env
```
2. **Edit `.env`** with your configuration:
- Set `DATABASE_URL` to your PostgreSQL connection string
- Update `CORS_ORIGINS` as needed
3. **Run migrations** (if using migrator app)
4. **Run the application**:
```bash
cargo run
```
The server will start on `http://0.0.0.0:{{app_port}}`.
## API Endpoints
| GET | `/health` | Health check |
### Example Request
```bash
curl http://localhost:{{app_port}}/health
```
## Adding New Features
Follow the hexagonal architecture pattern. See the gateway-template README for detailed examples.
### Quick Example
1. Create `src/features/users/mod.rs`, `handler.rs`, `service.rs`
2. Add routes in `src/main.rs`:
```rust
.route("/api/users", get(features::users::list_users))
```
## Configuration
All configuration is loaded from environment variables. See `.env.example`.
## Development
```bash
# Run with auto-reload
cargo watch -x run
# Run tests
cargo test
# Check code
cargo clippy -- -D warnings
# Format code
cargo fmt
```
## Database
Uses SeaORM with PostgreSQL. Generate entities after migrations:
```bash
sea-orm-cli generate entity -o src/adapters/entities
```
## When to Use This Template
Use the **api-service-template** when:
- Building internal microservices
- Auth is handled by API gateway
- No authentication needed (admin tools, etc.)
Use the **gateway-template** when:
- Building user-facing APIs
- Need session or JWT authentication
- Direct client access
## License
See workspace LICENSE