Developer guide: your own widget in 30 minutes¶
This guide builds a small but real widget — quote of the day — from an empty checkout to a pull request. Every step names the test that belongs to it and the command to run. The code below was produced by following this guide on a fresh clone (tool time about two minutes; reading and typing make it roughly half an hour).
The rules are enforced by tools (internal/archtest, depguard, type
checks); this guide explains why they exist.
0. Setup (≈ 5 min)¶
git clone https://github.com/itadori26/waylight.git && cd waylight
make deps && make ci
See CONTRIBUTING.md for running the app with hot reload.
1. The dependency rule in one picture¶
flowchart LR
subgraph module["internal/modules/quotes"]
domain["domain\nentities + rules"]
usecase["usecase\ninput ports, output ports"]
adapter["adapter\ncontroller · presenter · gateway"]
root["module.go\nwiring only"]
end
platform["internal/platform\nHTTP, SQLite, clock"]
web["web/src/features/quotes\ndomain · usecase · adapter/api · ui"]
usecase --> domain
adapter --> usecase
adapter --> domain
root --> adapter
root --> platform
web -. "HTTP + generated types" .-> adapter
Arrows point inwards: the domain knows nothing, the use cases know the
domain and declare the ports they need (Repository, Clock), adapters
implement those ports. That is why you can test a use case with an in-memory
fake, swap SQLite for something else, or run the whole app against fixtures
in demo mode — without touching the business rules.
2. Scaffold the module (≈ 2 min)¶
make new-module NAME=quotes TITLE="Quote of the day"
make ci # the untouched scaffold is green
The generator creates all rings with an example Item entity (here: the
quote text in Title), a SQLite table, CRUD endpoints, a widget and tests,
and wires it up with files of its own (cmd/server/module_quotes.go,
web/src/app/widgets/quotes.ts, web/src/app/services/quotes.ts, the
i18n/en.ts and de.ts of the feature, the German backend messages); no
existing file changes. The widget can already add and delete quotes.
3. Domain: the rule (≈ 5 min)¶
The business rule is "a different quote every day, the same one all day". It is pure logic, so it belongs in the domain and needs no mocks to test.
internal/modules/quotes/domain/pick.go:
// PickForDay returns the quote for the given day: every day the next quote,
// the same quote all day long, and the same choice on every device.
func PickForDay(quotes []Item, day time.Time) (Item, bool) {
if len(quotes) == 0 {
return Item{}, false
}
y, m, d := day.Date()
days := time.Date(y, m, d, 0, 0, 0, 0, time.UTC).Unix() / 86400
return quotes[int(days%int64(len(quotes)))], true
}
Add a domain error next to the generated one in domain/item.go:
// ErrNoQuotes is returned by the quote of the day while the list is empty.
var ErrNoQuotes = kernel.NewPublicError(kernel.ErrNotFound, "Add a quote first.")
Test (domain/pick_test.go): same quote in the morning and the evening,
another one tomorrow, false for an empty list.
go test ./internal/modules/quotes/domain/
kernel.NewPublicError wraps an error kind; the HTTP layer maps
ErrNotFound to 404 and shows the message to the user. The domain never
imports net/http.
4. Use case: the application flow (≈ 5 min)¶
Add the method to the input port in usecase/usecase.go and implement it
with the ports the use case already has:
// Today returns the quote of the day.
Today(ctx context.Context) (domain.Item, error)
// Today implements Quotes.
func (u *uc) Today(ctx context.Context) (domain.Item, error) {
items, err := u.List(ctx)
if err != nil {
return domain.Item{}, err
}
q, ok := domain.PickForDay(items, u.d.Clock.Now())
if !ok {
return domain.Item{}, domain.ErrNoQuotes
}
return q, nil
}
The time comes from the kernel.Clock port, not time.Now(), so the test
controls it. Test (usecase/usecase_test.go) with the generated in-memory
repository: empty list → kernel.ErrNotFound, one quote → that quote.
go test ./internal/modules/quotes/usecase/
5. Gateway: storage (≈ 0 min)¶
Nothing to do: the generated SQLite repository and its migration
(adapter/gateway/migrations/0001_init.sql) already store quotes. If you
change the schema, add a new migration file — never edit an applied one —
and extend adapter/gateway/sqlite_test.go, which runs against a real
temporary database.
6. Controller and route (≈ 3 min)¶
adapter/controller/handlers.go:
// Today handles GET /api/quotes/today.
func (h *Handlers) Today(w http.ResponseWriter, r *http.Request) {
q, err := h.uc.Today(r.Context())
if err != nil {
httpapi.WriteDomainError(w, r, err)
return
}
httpapi.WriteJSON(w, http.StatusOK, presenter.Item(q))
}
module.go — register the route behind the session guard:
r.Protected("GET /api/quotes/today", m.handlers.Today)
Controllers only translate HTTP ↔ use case; the presenter maps the entity to
a DTO so internal fields never leak. Document the endpoint in
api/modules/quotes.yaml (make openapi merges and validates the fragments). If you add or change a DTO, run make generate: the
TypeScript types in web/src/shared/api-client/generated/ are generated
from the Go structs, so frontend and backend cannot drift apart.
7. Frontend feature (≈ 7 min)¶
The frontend has the same rings in web/src/features/quotes/.
Output port and use case (usecase/quotesUseCases.ts):
today(): Promise<QuotesItem | null>; // in QuotesGateway
/** The quote of the day, or null while there is none. */
today(): Promise<QuotesItem | null> { // in QuotesUseCases
return this.gateway.today();
}
API adapter (adapter/api/quotesApi.ts) — a 404 is "no quote yet", not an
error:
async today(): Promise<QuotesItem | null> {
try {
return toItem(await this.http.get<ItemDTO>('/api/quotes/today'));
} catch (err) {
if (err instanceof ApiError && err.status === 404) return null;
throw err;
}
}
Widget (ui/QuotesWidget.svelte) — load both and show the quote above the
list:
const load = () =>
Promise.all([quotes.list(), quotes.today()])
.then(([l, q]) => ((items = l), (today = q), (error = '')))
.catch((err) => (error = errorMessage(err)));
{#if today}<blockquote class="today">{today.title}</blockquote>{/if}
Add today: vi.fn() to the gateway fake in usecase/quotesUseCases.test.ts
(the type checker tells you). Every visible text goes through t('…') with
keys in web/src/features/quotes/i18n/en.ts and de.ts.
cd web && npx svelte-check && npx vitest run src/features/quotes
8. Registry and the widget picker (≈ 1 min)¶
The generator already created the widget definition
web/src/app/widgets/quotes.ts (kind, title, description, default size) and
registered the module in cmd/server/module_quotes.go. The backend reports the module's WidgetKinds(),
so the widget only appears in the picker when the module is enabled
(MODULES_DISABLED=quotes hides it). Once the grouped picker (#104) is in
place, also give the definition a category and an icon.
Optional: answer in the smart search (#161). If the module has something worth
asking for ("next waste collection", "speed test"), add
web/src/app/search/quotes.ts: defineSearch({ module: 'quotes', intents, source }).
Intents are data (weighted terms, optional prefixes and slots), the source wraps
your use cases and returns a text, metric, list, status or action answer. It is
collected by convention, the engine stays untouched. Copy search/speedtest.ts
and add a few queries to the table in search/search.test.ts.
9. Pull request¶
make ci && make smoke
git switch -c feat/quotes && git commit -am "feat(quotes): quote of the day widget"
Open a PR that says Closes #<issue>, fill in the checklist (no new
dependency or a justification, budgets green — see
ADR 0011) and describe how you tested it.
Checklist for a new integration¶
When the widget talks to another system (see the integrations roadmap #91):
- [ ] Domain types describe what the widget shows, not the vendor's JSON
- [ ] The use case depends on a provider port; the vendor client is a gateway adapter
- [ ] Opt-in outbound requests: nothing is contacted until the user saves a URL; timeouts set; results cached in the use case; host listed in outbound requests
- [ ] Secrets encrypted through the
Cipherand only returned as "set / not set" - [ ] Gateway tested against an
httptest.Serverwith recorded responses - [ ] Category and icon for the widget picker (#104); texts in both catalogues
- [ ] Optional fixture in
internal/platform/demo/transport.goso the demo shows it - [ ] Anything that only needs one value from a JSON endpoint can use the generic JSON widget (#48) instead