Skip to content
Skills Library
Programming · Building & coding

services-layer

/services-layer

Apply Whispering service-boundary patterns for UI-free capabilities, explicit inputs, Result fallibility, Live objects, lifecycle factories, and platform variants. Use when creating or refactoring services, contracts, provider dispatch, or the `$lib/services` barrel.

Repository
epicenter ↗
Licence
MIT
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Apply Whispering service-boundary patterns for UI-free capabilities, explicit inputs, Result fallibility, Live objects, lifecycle factories, and platform variants. Use when creating or refactoring services, contracts, provider dispatch, or the `$lib/services` barrel.

Original author description

Apply Whispering service-boundary patterns for UI-free capabilities, explicit inputs, Result fallibility, Live objects, lifecycle factories, and platform variants. Use when creating or refactoring services, contracts, provider dispatch, or the `$lib/services` barrel.

How it works

  1. Product Sentence
  2. Boundary
  3. Model Fallibility Honestly
  4. Direct Object Or Factory
  5. Platform And Runtime Selection
  6. Service Barrel
  7. Final Check
Original SKILL.md headings · 121 lines, 644 words
SKILL.md preview
---
name: services-layer
description: Apply Whispering service-boundary patterns for UI-free capabilities, explicit inputs, Result fallibility, Live objects, lifecycle factories, and platform variants. Use when creating or refactoring services, contracts, provider dispatch, or the `$lib/services` barrel.
metadata:
  author: epicenter
  version: '3.0'
---

# Services Layer

This skill was grounded in Whispering's `src/lib/services` and its
`#platform/*` mappings. Both were removed when Whispering became a standalone
file-folder app, so every `apps/whispering/...` path below is historical. The
patterns still apply; ground new work in the app you are editing and its own
`package.json`. Neighboring skills are leads, not current architecture.

## Product Sentence

The service layer owns UI-free capabilities; callers inject app policy through
explicit inputs, fallible operations return Results, and platform selection has
one build-time owner.

## Boundary

Services may perform IO and may own service-local runtime state. They are not
required to be pure functions. They must remain free of UI and app-owned policy:

- no runtime reads of Svelte stores, `settings`, `deviceConfig`, toasts, or
  `report`;
- accept credentials, model names, endpoints, paths, and user choices as inputs;
- return domain data and errors, not presentation copy or UI state;
- expose the same contract from both sides of a `#platform/*` seam.

`$lib/operations` usually reads app settings, chooses providers, and composes
services. `$lib/queries` adds shared query identity and observable lifecycle only
when the UI needs it.

The transcription directory also holds provider registry data and the
UI-facing `provider-ui.ts` join. Those colocated metadata modules are not
service implementations; do not use them to weaken the service boundary.

## Model Fallibility Honestly

Use `Result<T, E>` for a public operation that can fail in ordinary runtime use.
Adapt throwing platform or library calls with the `error-handling` skill.

Do not fake a Result for an infallible in-memory action or cleanup. Current
examples include local shortcut `register` / `unregister` returning `void` and
listener setup returning a cleanup function.

```typescript
export type DownloadService = {
	downloadBlob(args: {
		name: string;
		blob: Blob;
	}): Promise<Result<void, DownloadError>>;
};
```

Errors belong to the layer that understands the failure. Preserve lower-layer
tagged errors when composing services. Define a service-local variant only for
a failure the service itself owns. Use `error-handling` for variant shape,
message rules, adaptation, and propagation.

## Direct Object Or Factory

Default to a direct `*ServiceLive` object when construction has no input or
lifecycle. Current download, analytics, text, and transcription provider
implementations use this shape. Download, analytics, and text check their shared
platform contracts with `satisfies <Service>`.

Use a factory when it owns real construction inputs, replaceable dependencies,
or stateful lifecycle. The browser and CPAL recorder factories earn their
boundary because each creates recording sessions with stop, cancel, subscribe,
and teardown behavior.

Do not add `create*` plus `*Live` mechanically for a stateless object.

Read [service implementation patterns](references/service-implementation-pattern.md)
for the current direct-object example and the factory decision.

## Platform And Runtime Selection

Use `#platform/*` imports for a capability with browser and Tauri
implementations. `package.json#imports` chooses the implementation at build
time; shared callers import one stable name and do not inspect
`window.__TAURI_INTERNALS__`.

Use the nullable `#platform/tauri` namespace for Tauri-only capabilities.

User-selected providers are runtime policy, not a platform seam. Keep the
dispatch in the consuming operation. Whispering transcription reads the
selected provider in `$lib/operations/transcribe.ts`; the query layer only
observes that operation.

Read [service organization and platform variants](references/service-organization-platforms.md)
when adding or moving a platform service.

## Service Barrel

`$lib/services/index.ts` collects stable cross-platform capabilities:

```typescript
export const services = {
	analytics: AnalyticsServiceLive,
	text: TextServiceLive,
	blobs: BlobsLive,
	blobSources: BlobSourcesLive,
	download: DownloadServiceLive,
	localShortcutManager: LocalShortcutManagerLive,
	sound: PlaySoundServiceLive,
} as const;
```

Do not force every provider implementation into this barrel. A runtime
operation may import its provider-specific services directly when it owns the
dispatch table.

## Final Check

- The service imports no UI or app-owned settings.
- Every app choice enters as an explicit input or is selected by the caller.
- Fallible public operations return Results; infallible operations stay plain.
- A factory owns construction or lifecycle, not convention alone.
- Platform choice happens through one `#platform/*` mapping.
- Runtime provider choice happens once at the consuming operation.
- Lower-layer errors pass through unless this service owns a new failure.
Files in this package (3)
  • SKILL.md 5 KB
  • references/service-implementation-pattern.md 2 KB
  • references/service-organization-platforms.md 3 KB

Versions

The database has no other skills named services-layer.

Database snapshot: 13.11.2026 · package version 8b6572447673 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100integration-testing
    Integration testing patterns for database state, API contracts, service boundaries, and component wiring. Use when testing how multiple parts of a system work together without mocks.
  • 100managedcode-communication
    Use ManagedCode.Communication when a .NET application needs explicit result objects, structured errors, and predictable service or API boundaries instead of exception-driven control flow. USE FOR: integrating ManagedCode.Communication into services or APIs; replacing…
  • 100map-systems
    Creates a visual and textual map of the project systems, services, data flows, and integration boundaries. Use when documenting system architecture or when the user mentions system map, architecture diagram, or service boundaries.
  • 100adding-service-documentation
    Add or update Coolify one-click service documentation in content/docs/services/, store logos in public/images/services/, and regenerate the service catalog. Use for service pages and catalog updates; use adding-documentation-pages for other guides.
  • 100nestjs-oop-design-patterns
    Applies pragmatic OOP, SOLID, object-design rules, and design patterns to NestJS and TypeScript code. Use when writing or refactoring controllers, providers, use cases, entities, value objects, repositories, adapters, factories, strategies, handlers, or tests; when diagnosing…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.