GKaszewski/movies-diary
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update for new crate layout

Browse Source
This commit is contained in:
Gabriel Kaszewski
2026-10-25 22:58:46 +01:00
parent b76f5996da
commit 80072eb463
20 changed files with 148 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
README.md
View File

@@ -93,6 +93,7 @@ Hexagonal (Ports & Adapters) with Domain-Driven Design:
api-types — shared REST API request/response DTOs (Serialize/Deserialize + utoipa schemas) + HtmlPageContext; used by http-axum and tui
config — typed configuration (defaults, config.toml, legacy env names); loaded once by the binaries
bootstrap — composition root: the only crate that names adapters; builds the server router and the worker service
event-payload — serde payloads for domain events, shared by the NATS and SQLite-queue adapters
domain — pure types and CQRS port traits (MovieCommand/MovieQuery, WatchEventCommand/WatchEventQuery, GoalCommand/GoalQuery, DiaryQuery, PersonCommand/PersonQuery, SearchCommand/SearchPort, SocialCommand/SocialQuery, ImageFetcher, RssFeedRenderer), no external deps except serde
application — use cases (commands + queries), business logic orchestration; handlers delegate here for all domain logic; modules: auth, diary, goals, import, integrations, movies, person, search, social, users, watchlist, wrapup
server — thin HTTP binary (dotenv, config, bootstrap::build_server, axum::serve); features (federation, nats) forward to bootstrap
@@ -100,7 +101,7 @@ worker — thin worker binary (bootstrap::build_worker, run until c
adapters/
http-axum — Axum HTTP adapter: JSON API, classic HTML UI (askama templates), OpenAPI spec, Swagger UI + Scalar, federation-gated routes; library crate, no binary of its own
auth — JWT issuance and validation (Argon2 passwords)
sqlite — SQLite repositories, search (FTS5), social graph, durable event queue, connection factory + migrations
sqlite — SQLite repositories (one module per aggregate under repositories/), search (FTS5), social graph, durable event queue, connection factory + migrations; the only storage adapter
metadata — TMDB / OMDb HTTP client
poster-fetcher — downloads poster images
object-storage — stores images (posters + user avatars) on local filesystem or S3-compatible storage
@@ -110,10 +111,10 @@ adapters/
export — CSV and JSON diary serialization
importer — CSV/TSV/JSON/XLSX parser and column mapper for bulk import
media-server — Jellyfin and Plex webhook payload parsers (MediaServerParser adapter; Plex requires Plex Pass)
event-publisher — in-memory event channel (used in tests)
event-publisher — in-memory event channel
nats — NATS Core / JetStream event publisher and consumer
activitypub — ActivityPub federation adapter (follow, inbox/outbox, actor); delegates to k-ap for protocol internals
sqlite-federation — SQLite-backed federation repository
sqlite-federation — SQLite-backed federation repository (k-ap trait implementations; only built with the `federation` feature)
tui — terminal UI client (ratatui); shares api-types with http-axum for typed API access
spa/ — React SPA (TanStack Router + shadcn/ui + Vite); served at /app/ by the backend
```
@@ -127,7 +128,13 @@ spa/ — React SPA (TanStack Router + shadcn/ui + Vite); served a
## Configuration
Copy `.env.example` to `.env` and set the values below. Required fields must be set before the server will start.
Settings are layered, later sources winning:
1. built-in defaults
2. `config.toml` in the working directory, or the file named by `CONFIG_FILE` (a named file that does not exist is an error; the default `config.toml` is optional)
3. environment variables (including those from `.env`), under the names in the table below
Copy `.env.example` to `.env` and set the values you need. Malformed values (a non-numeric `PORT`, an unknown `EVENT_BUS_BACKEND`) fail startup with a message naming the setting. An empty value (`PORT=`) counts as unset, so the default applies. The variable names are unchanged from earlier releases; every one maps to a `section.field` key in `config.toml` (for example `PORT` is `server.port`, `JWT_SECRET` is `auth.jwt_secret`).
| Variable | Default | Required | Description |
|---|---|---|---|
@@ -155,6 +162,17 @@ Copy `.env.example` to `.env` and set the values below. Required fields must be
| `EVENT_BUS_BACKEND` | `db` | No | `db` (default) or `nats` |
| `NATS_URL` | — | NATS only | NATS connection URL (e.g. `nats://localhost:4222`) |
Required fields must be set (in either source) before the server will start.
### Cargo features
| Feature | Default | Effect |
|---|---|---|
| `federation` | yes | ActivityPub federation (`activitypub`, `sqlite-federation`, federation routes) |
| `nats` | no | NATS event bus (`EVENT_BUS_BACKEND=nats`) |
Build without federation with `--no-default-features`. `sqlite` and `sqlite-federation` are deprecated aliases kept so old build commands still work.
The `worker` binary must run alongside `server` to process events:
```bash
@@ -208,23 +226,26 @@ Supports review logging, bulk CSV import, and diary browsing.
A `Makefile` wraps the most common dev commands:
```bash
make # default: fmt-check + clippy + test (same order as CI)
make # make check: the full gate, same steps as CI
make fix # auto-apply fmt + clippy fixes
make fmt # apply rustfmt
make clippy # clippy with -D warnings
make test # cargo test
make test # cargo test --workspace
```
`make check` runs fmt-check, clippy, tests (default features and `--no-default-features`), and the layering guards (see `CONTRIBUTING.md`).
## Test
```bash
cargo test # full workspace (requires DATABASE_URL for sqlx offline checks)
cargo test -p application # business logic tests only — no database required
cargo test --workspace # everything; needs no external services
cargo test -p application # business logic tests only — in-memory fakes, no database
cargo test -p domain # domain model + value object tests
cargo test -p bootstrap # route smoke, API and handler tests over the real wiring
cargo llvm-cov -p application -p domain # line coverage report (requires cargo-llvm-cov)
```
The `application` and `domain` crates have 400+ unit tests covering all use case modules (auth, diary, goals, import, integrations, movies, person, search, users, watchlist, wrapup) backed by in-memory fakes from `domain`'s `test-helpers` feature. These run without a database and are the fastest feedback loop for business logic changes.
Each crate keeps its tests in `crates/<crate>/tests/`. The `application` and `domain` crates have 400+ tests covering all use case modules (auth, diary, goals, import, integrations, movies, person, search, users, watchlist, wrapup) backed by the in-memory fakes and factories in `domain::testing` (the `test-helpers` feature). They are the fastest feedback loop for business logic changes.
## Docker