docs: add architecture and best-practices reference guides

[aseguragonzalez]

Summary

• Add docs/architecture.md: describes the standard service building blocks (API, Database, Subscriber, DLQ Subscriber, Publisher, Scheduler, Worker) with Mermaid diagrams and infrastructure mechanisms (outbox pattern, unit of work, idempotency, retry/DLQ, observability).
• Add docs/best-practices.md: concise DDD & Hexagonal Architecture reference covering domain components (Entity, Value Object, Aggregate, Domain Event, Domain Service, Repository, Ports), application components (Command/Query/Handler, UoW, Result, Maybe), and the domain event vs integration event vs background task decision guide.

Test plan

• All markdownlint rules pass (make pre-commit)
• Conventional Commit hook passes
• No changes to source code — documentation only

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds two new reference guides under docs/ to describe the seedwork’s intended service architecture and DDD/hexagonal best practices, including diagrams and decision guides for events vs tasks.

Changes:

• Added a DDD & Hexagonal Architecture best-practices guide with component definitions and recommended flows.
• Added a service architecture building-blocks guide covering outbox/UoW/idempotency/retry/DLQ/observability, with Mermaid diagrams.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
docs/best-practices.md	New reference guide for DDD/hexagonal rules, domain/application components, and event/task decisioning.
docs/architecture.md	New reference guide describing standard service building blocks and infrastructure mechanisms (outbox, UoW, idempotency, retry/DLQ, observability).

Comments suppressed due to low confidence (1)

docs/best-practices.md:345

• This section documents a Maybe type with just(...) / nothing() helpers, but no such type/helpers exist in the repository; queries return None when absent. Please align this section with the actual API (or add the missing Maybe implementation), otherwise readers will look for APIs that aren't there.

### 3.6 Maybe

`Maybe` is the **value-based absence contract for queries**.

#### Key points

- Two states: `just(value)` (found) and `nothing()` (absent).
- Replaces `null`/`None` returns with an explicit type that forces the caller to handle absence.
- Use `nothing()` for both not-found and unauthorized — identical response, no information leak.

#### Do

- Check `isNothing()` at the entry point before accessing the value.

#### Don't

- Use `Maybe` for command results — that is `Result`'s responsibility.
- Use `just(null)` — if the value is absent, return `nothing()`.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.