Skip to content

Service Template¶

Use this template when adding a new application service or use case in src/application/. It complements the code review checklist in ../development/coding-standards.md.

# <Service/UseCase Name>

## Overview

What this service does and which feature it serves.

## Responsibilities

- what it owns
- what it explicitly does **not** do (boundaries)

## Dependencies

| Dependency | Contract (interface)                         | Implementation                             |
| ---------- | -------------------------------------------- | ------------------------------------------ |
| Repository | `…Repository` (`src/application/interfaces`) | `…PrismaRepository` (`src/infrastructure`) |
| Cache      | `CacheService`                               | Redis                                      |
| Provider   | `…Service`                                   | `…` (S3 / FCM / SMTP / SMS / Zwitch)       |

## API surface

```typescript
class <Name>Service {
  async run(input: <CommandInput>): Promise<Result>;
}
```

Behavior / business rules¶

Numbered rules, including validation and error cases. Keep business logic here — not in controllers.

Flow¶

sequenceDiagram
    participant C as Controller
    participant S as <Service>
    participant R as Repository
    participant DB as PostgreSQL
    C->>S: run(input)
    S->>S: validate + authorize
    S->>R: persist
    R->>DB: write
    S-->>C: result

Error cases¶

Condition	Thrown error	HTTP mapping

Testing¶

Unit test fakes for each dependency.
Happy path + empty + error cases (see ../development/testing.md).

---

## Rules

- Depend on **interfaces**, never on infrastructure classes directly.
- Register the implementation in `src/infrastructure/di.ts`.
- If a write spans multiple DB operations, use `unitOfWork`.

## Checklist

- [ ] Constructor injection of contracts only
- [ ] Business rules in the service, not the caller
- [ ] Typed errors used
- [ ] Unit tests added
- [ ] Registered in DI