[New Application] Intitial Draft of The Chat Service

[lcox74]

The Chat Service is the whole point of this project. Right now, we’ve only got a rough high-level outline in docs/content/docs/design/chat-service.mdx and a lot of it will probably change once we start building. The goal here is to get a first working draft, something we can run locally, poke at, and use to figure out what the real implementation should look like.

Proposed Scope

The initial draft should include three main subsystems:

1. Write-Ahead Log (WAL): Provides durable, append-only storage for messages.
2. Notifier (Pub/Sub Broker): Fans out new message offsets to subscribed clients.
3. Simple API Layer: Exposes HTTP endpoints for publishing, retrieving, and streaming messages.

1. Write-Ahead Log (WAL)

The Write-Ahead Log (WAL) is the backbone of the chat service, it ensures every message is durably stored in order before being made visible to readers. It’s designed as an append-only sequence of message batches on disk, backed by a lightweight in-memory index for fast lookups. The WAL provides the core durability and ordering guarantees for all downstream components, especially the Notifier. A single writer goroutine will handle all appends to maintain consistency and minimize contention.

• Append-only disk log segmented into files (e.g., 64–256 MB each) with CRC checks per batch.
• Batched, asynchronous writes (time or size triggered) for throughput.
• Rebuildable in-memory index sampling offsets for efficient random access.
• Fixed-size ring buffer for hot reads and non-blocking writer semantics.

2. Notifier (Pub/Sub Broker)

The Notifier is responsible for broadcasting new message events to connected clients in real time. It subscribes to committed offsets from the WAL and delivers them to interested consumers through a lightweight publish-subscribe (Pub/Sub) mechanism. The initial implementation focuses on simplicity and reliability, providing a foundation for more advanced delivery models later.

• Subscribes to WAL commit events to detect new messages.
• Pushes updates to connected clients using long-polling.
• Maintains per-connection state for delivery continuity.
• Optimized for minimal latency and low memory overhead.

3. Simple API

The API layer exposes a minimal but functional HTTP interface for publishing and retrieving messages. It sits on top of the WAL and Notifier, enabling clients to post new messages, fetch recent ones, and subscribe to live updates. Authentication is enforced early on to ensure secure access and consistent user identity handling.

Endpoint	Method	Description
/v1/messages	POST	Append a new message.
/v1/messages	GET	Fetch recent messages.
/v1/sync	GET	Long-poll for live messages (30 s timeout).

Note: JWTs given by the Auth service’s can be verified using the/v1/.well-known/jwks.json endpoint, and the the user’s name and ID can be fetched from the JWT itself or the /v1/oauth2/introspect endpoint.

Implementation Notes

• This version will not implement chat rooms; focus on basic message flow and reliability.
• Maybe follow the event schema guidelines outlined in docs/content/docs/design/events.mdx, they serve as references, not strict contracts.
• Add robust testing for all subsystems: WAL consistency, recovery, notification delivery, and API behavior.

Could also be good to include some docs or a RFD on the message/event structure chosen and used.