rust-template/README.md

# rust-template

RustRover-ready fullstack starter: Axum + PostgreSQL + sqlx on the backend, Vue 3 + TypeScript + Tailwind 4 on the frontend.

The backend route table is the API contract. `utoipa-axum` builds OpenAPI from the same handlers Axum serves. `just generate-api` writes `packages/contracts/openapi.json` and a typed Vue client. Vite reads `config/*.toml` and reverse-proxies `/api` and `/health` to the server bind address.

## Layout

```
config/                  shared TOML (server + Vite)
apps/server/             Axum, sqlx, request logging, OpenAPI
apps/web/                Vue 3 + TS + Tailwind
packages/contracts/      generated openapi.json
scripts/generate-api.mjs typed client from that spec
infra/compose/           local Postgres
```

## Run it

```bash
cp .env.example .env
docker compose -f infra/compose/docker-compose.yml up -d postgres
cargo run -p server
```

```bash
cd apps/web && npm install && npm run dev
```

- UI: http://127.0.0.1:5173
- API: http://127.0.0.1:8080
- Swagger: http://127.0.0.1:8080/api/docs

Vite binds `127.0.0.1` on purpose. `localhost` can resolve to `::1` and miss the proxy.

## RustRover

Open the repo root. Run `cargo run -p server` with `APP_ENV=development`.

To use this as a New Project template: Settings → Languages & Frameworks → Rust → custom cargo-generate template → paste the Git URL of this repo.

## Config

Load order:

1. `config/default.toml`
2. `config/{APP_ENV}.toml`
3. `APP__SECTION__KEY` environment variables

```bash
APP__SERVER__PORT=9000 cargo run -p server
```

Both processes honor `APP_CONFIG_DIR` if you need the files somewhere else.

## Add an endpoint

1. Handler + `#[utoipa::path(...)]`
2. `.routes(routes!(your_handler))` in `apps/server/src/routes/mod.rs`
3. `just generate-api`
4. Import the new function from `apps/web/src/api/generated.ts`

Request logs include method, path, status, latency, and `X-Request-Id`.

## Useful commands

```bash
just server
just web
just generate-api
just check
```