init: scaffold from k-template with postgres + worker

README.md

@@ -0,0 +1,137 @@
+# k-template
+
+A cargo-generate template for personal Rust web services. Gives you auth, persistence, logging, CORS, and API docs out of the box so you can start writing domain code immediately.
+
+Follows the same hexagonal/ports-and-adapters architecture used in [thoughts](https://git.gabrielkaszewski.dev/GKaszewski/thoughts) and [movies-diary](https://git.gabrielkaszewski.dev/GKaszewski/movies-diary).
+
+## What you get
+
+- **Full hexagonal architecture** — `domain` → `application` → `adapters` → `presentation` → `bootstrap`, each as a separate crate with clear boundaries
+- **JWT auth wired end-to-end** — register, login, and `GET /auth/me` working from day one
+- **SQLite or PostgreSQL** — chosen at generation time, migrations included
+- **CORS + structured logging** — tower-http middleware configured in bootstrap
+- **Scalar API docs** at `/scalar`, OpenAPI JSON at `/api-docs/openapi.json`
+- **Optional worker binary** — tokio-based background job runner with an example job
+- **Optional OIDC stub** — placeholder adapter for OAuth2/OpenID Connect flows
+- **Docker-ready** — multi-stage Dockerfile with dependency layer caching, no live DB needed at build time
+
+## Generate a new project
+
+```bash
+cargo generate --git https://git.gabrielkaszewski.dev/GKaszewski/k-template.git
+```
+
+You'll be prompted for:
+
+| Option | Choices | Default |
+|--------|---------|---------|
+| `project_name` | any snake_case string | — |
+| `database` | `sqlite`, `postgres` | `sqlite` |
+| `worker` | bool | false |
+| `auth_oidc` | bool | false |
+
+## Generated project structure
+
+```
+crates/
+  domain/               pure Rust — entities, value objects, port traits, errors
+  application/          use cases (RegisterUser, LoginUser, GetProfile) + test fakes
+  api-types/            shared request/response DTOs with OpenAPI derives
+  adapters/
+    sqlite/             sqlx SQLite UserRepository + migrations
+    postgres/           sqlx PostgreSQL UserRepository + migrations
+    auth/               BcryptPasswordHasher, JwtTokenIssuer, OidcAdapter stub
+  presentation/         axum handlers, JwtClaims extractor, routes, Scalar mount
+  bootstrap/            Config from env, factory wiring, main entry point
+  worker/               (optional) Job trait, JobRunner, ExampleJob, WorkerConfig
+```
+
+## Running locally
+
+```bash
+cp .env.example .env
+cargo run -p bootstrap
+```
+
+The server starts at `http://localhost:3000`.
+
+## Endpoints (out of the box)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `POST` | `/api/v1/auth/register` | — | Create account → `AuthResponse` |
+| `POST` | `/api/v1/auth/login` | — | Login → `AuthResponse` |
+| `GET`  | `/api/v1/auth/me` | Bearer | Current user profile |
+| `GET`  | `/health` | — | `{"status":"ok"}` |
+| `GET`  | `/scalar` | — | Interactive API docs |
+| `GET`  | `/api-docs/openapi.json` | — | OpenAPI spec |
+
+```bash
+# Register
+curl -s -X POST http://localhost:3000/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"me@example.com","password":"password123"}' | jq
+
+# Login and get token
+TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"me@example.com","password":"password123"}' | jq -r '.token')
+
+# Profile
+curl -s http://localhost:3000/api/v1/auth/me \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_URL` | `sqlite://data.db` | Database connection string |
+| `JWT_SECRET` | *(required)* | Signing secret — min 32 chars in production |
+| `HOST` | `0.0.0.0` | Bind address |
+| `PORT` | `3000` | Listen port |
+| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | Comma-separated allowed origins |
+
+## Tests
+
+```bash
+# Unit tests (no DB required)
+cargo test -p domain -p application -p adapters-auth
+```
+
+13 unit tests cover email validation, use case logic (register/login/get_profile), bcrypt roundtrip, and JWT encode/verify.
+
+## Docker
+
+```bash
+# Build
+docker build -t my-app .
+
+# Run
+docker run -p 3000:3000 \
+  -e DATABASE_URL=sqlite:///data/app.db \
+  -e JWT_SECRET=change-me-32-chars-minimum-here \
+  my-app
+```
+
+Or with compose:
+
+```bash
+docker compose up
+```
+
+The Dockerfile uses dependency layer caching (manifests copied and fetched before source) so rebuilds after source-only changes are fast. No live database is needed at compile time — the `.sqlx` offline cache is committed.
+
+## What to do after generating
+
+1. Add your domain entities and value objects to `crates/domain/`
+2. Write use cases in `crates/application/`
+3. Add DB columns/tables via new migration files in `crates/adapters/sqlite/migrations/`
+4. Add handlers in `crates/presentation/src/handlers/`
+5. Wire new use cases in `crates/bootstrap/src/factory.rs`
+
+Auth, CORS, logging, and docs are already done — focus on what makes your project unique.
+
+## License
+
+MIT