# nukopy/engawa architecture

> Architecture diagram of the GitHub repository nukopy/engawa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nukopy/engawa
- Repository: https://github.com/nukopy/engawa

## Overview

1. **Repository shape**
   - This is a Cargo workspace with three publishable packages:
     - `packages/server` — the main chat server
     - `packages/client` — a CLI chat client
     - `packages/shared` — small cross-cutting utilities
   - The root also contains workspace-level tests, CI, docs, ADRs, and task scripts.

2. **System boundary**
   - The runtime system is a **WebSocket-based chat service**.
   - The server is the central hub: clients connect to it, send chat events, and receive broadcasts from other participants.
   - The client is interactive CLI software, not a browser app.

3. **Server entrypoint and outer adapter**
   - `packages/server/src/bin/server.rs` starts the server process.
   - The `ui` layer is the outermost adapter for the server:
     - `ui/server.rs` wires the application together
     - `ui/handler/http.rs` handles HTTP endpoints, likely including connection setup and status checks
     - `ui/handler/websocket.rs` handles WebSocket upgrades and message exchange
     - `ui/state.rs` and `ui/signal.rs` manage runtime state and shutdown signaling

4. **Server layered architecture**
   - The server is explicitly split into four architectural layers:
     - **UI**: HTTP/WebSocket handlers and process lifecycle
     - **Usecase**: application orchestration
     - **Domain**: entities, value objects, repository and message-pusher contracts
     - **Infrastructure**: concrete repository/message transport implementations and DTO mapping
   - The docs and ADRs indicate this layering is intentional and central to the design.

5. **Use case layer responsibilities**
   - `packages/server/src/usecase/*` contains the operations exposed by the server:
     - connect/disconnect participant
     - send message
     - get room list, room detail, room state
   - These use cases are the main coordination point between request handling and the domain model.
   - They likely enforce rules such as duplicate client rejection and participant lifecycle updates.

6. **Domain model**
   - `packages/server/src/domain/*` holds the core chat concepts:
     - entities and value objects
     - repository abstraction
     - message pusher abstraction
     - factory and domain-specific errors
   - This is where the rules for room/participant/message state belong, independent of HTTP, WebSocket, or storage technology.
   - The `message_pusher` abstraction is a notable boundary: domain/use cases depend on an interface, not directly on WebSocket details.

7. **Infrastructure layer**
   - `packages/server/src/infrastructure/*` provides the concrete implementations behind domain contracts:
     - `repository/inmemory` for in-memory persistence
     - `repository/postgresql` for a database-backed option
     - `message_pusher/websocket.rs` for sending messages to connected clients
     - DTO conversion modules for translating between domain objects and wire formats
   - This layer is where external technology is isolated from the domain.

8. **Server data flow**
   - Typical flow is:
     1. client connects over HTTP/WebSocket
     2. UI handler converts the transport request into a use case call
     3. use case updates domain state through repositories
     4. domain events/state are converted to DTOs
     5. message pusher broadcasts to relevant connected clients
   - Broadcast behavior excludes the sender from receiving their own chat message, per the README.

9. **Client architecture**
   - `packages/client/src/bin/client.rs` is the CLI entrypoint.
   - The client is organized around:
     - `runner.rs` for orchestration
     - `session.rs` for connection/session lifecycle
     - `ui.rs` for terminal interaction
     - `formatter.rs` for rendering received events
     - `domain.rs` and `error.rs` for client-side models and failures
   - This keeps terminal UI, connection management, and message formatting separate.

10. **Client runtime behavior**
    - The client connects to the server using a unique `client_id`.
    - It supports automatic reconnection, which means the client has its own connection-state loop rather than being a thin transport wrapper.
    - Incoming server events such as room state, participant join/leave, and chat messages are formatted for CLI display.

11. **Shared package**
    - `packages/shared` provides reusable cross-cutting utilities:
      - logging
      - time handling
    - This package keeps common runtime concerns out of both server and client codebases and helps avoid duplicating infrastructure glue.

12. **Protocol and message shape**
    - The system exchanges structured chat events such as:
      - `room-connected`
      - `participant-joined`
      - `participant-left`
      - `chat`
    - There is an explicit DTO/conversion boundary on the server, suggesting the external wire format is intentionally separated from the domain model.

13. **Testing and quality gates**
    - Integration tests live at workspace level under `tests/` and cover HTTP and WebSocket behavior.
    - CI is defined in GitHub Actions, and the repo uses standard Rust tooling (`cargo fmt`, `clippy`, `cargo test`) plus `Taskfile.yml` for common workflows.
    - The test layout suggests the architecture is validated primarily through end-to-end protocol behavior, not just unit tests.

14. **Architecture diagram guidance**
    - For a diagram, show three main boxes:
      - **Client CLI**
      - **Server application**
      - **Shared utilities**
    - Inside the server, show layered sub-boxes from outer to inner: **UI → Usecase → Domain → Infrastructure**.
    - Show the main data path from client WebSocket traffic into the server UI, through use cases and domain state, then back out through the message pusher to other clients.

Main entry points: [`packages/server/src/domain/mod.rs`](https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/mod.rs) (Domain model), [`packages/server/src/ui/server.rs`](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/server.rs) (Server UI), [`packages/server/src/ui/handler/websocket.rs`](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/handler/websocket.rs) (WebSocket handler), [`packages/server/src/ui/handler/http.rs`](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/handler/http.rs) (HTTP handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
end

subgraph group_server["Server app"]
  node_server_bin["Server entry<br/>binary<br/>[server.rs]"]
  node_ui_server["Server UI<br/>adapter<br/>[server.rs]"]
  node_http_handler["HTTP handler<br/>transport handler<br/>[http.rs]"]
  node_ws_handler["WebSocket handler<br/>transport handler<br/>[websocket.rs]"]
  node_ui_state["UI state<br/>runtime state<br/>[state.rs]"]
  node_ui_signal["Shutdown signal<br/>lifecycle<br/>[signal.rs]"]
  node_connect_uc["Connect<br/>use case"]
  node_disconnect_uc["Disconnect<br/>use case"]
  node_send_uc["Send message<br/>use case<br/>[send_message.rs]"]
  node_rooms_uc["Room queries<br/>use case<br/>[get_rooms.rs]"]
  node_domain_core["Domain model<br/>[mod.rs]"]
  node_repo_contract["Repository contract<br/>domain port<br/>[repository.rs]"]
  node_pusher_contract["Message pusher<br/>domain port<br/>[message_pusher.rs]"]
  node_infra_repo["Repos<br/>infrastructure<br/>[mod.rs]"]
  node_infra_pusher["WS pusher<br/>infrastructure<br/>[websocket.rs]"]
  node_dto_map["DTO mapping<br/>infrastructure<br/>[conversion.rs]"]
end

subgraph group_client["Client CLI"]
  node_client_bin["Client entry<br/>binary<br/>[client.rs]"]
  node_runner["Runner<br/>orchestrator<br/>[runner.rs]"]
  node_session["Session<br/>connection lifecycle<br/>[session.rs]"]
  node_tui["Terminal UI<br/>presentation<br/>[ui.rs]"]
  node_formatter["Formatter<br/>presentation<br/>[formatter.rs]"]
end

subgraph group_shared["Shared utils"]
  node_shared_utils["Shared core<br/>utilities<br/>[lib.rs]"]
end

subgraph group_tests["Integration tests"]
  node_tests_http["HTTP tests<br/>integration test<br/>[http_api.rs]"]
  node_tests_ws_conn["WS connect<br/>integration test"]
  node_tests_ws_msg["WS messaging<br/>integration test"]
end

node_server_bin -->|"starts"| node_ui_server
node_ui_server -->|"routes"| node_http_handler
node_ui_server -->|"routes"| node_ws_handler
node_ui_server -->|"shares"| node_ui_state
node_ui_server -->|"stops"| node_ui_signal
node_http_handler -->|"calls"| node_connect_uc
node_http_handler -->|"calls"| node_rooms_uc
node_ws_handler -->|"calls"| node_connect_uc
node_ws_handler -->|"calls"| node_send_uc
node_ws_handler -->|"calls"| node_disconnect_uc
node_connect_uc -->|"uses"| node_domain_core
node_disconnect_uc -->|"uses"| node_domain_core
node_send_uc -->|"uses"| node_domain_core
node_rooms_uc -->|"uses"| node_domain_core
node_domain_core -->|"depends on"| node_repo_contract
node_domain_core -->|"depends on"| node_pusher_contract
node_repo_contract -.->|"implemented by"| node_infra_repo
node_pusher_contract -.->|"implemented by"| node_infra_pusher
node_infra_repo -->|"uses"| node_dto_map
node_infra_pusher -->|"uses"| node_dto_map
node_client_bin -->|"starts"| node_runner
node_runner -->|"manages"| node_session
node_runner -->|"drives"| node_tui
node_session -->|"feeds"| node_formatter
node_session -->|"updates"| node_tui
node_shared_utils -.->|"used by"| node_server_bin
node_shared_utils -.->|"used by"| node_client_bin
node_tests_http -.->|"verifies"| node_http_handler
node_tests_ws_conn -.->|"verifies"| node_ws_handler
node_tests_ws_msg -.->|"verifies"| node_send_uc

click node_server_bin "https://github.com/nukopy/engawa/blob/main/packages/server/src/bin/server.rs"
click node_ui_server "https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/server.rs"
click node_http_handler "https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/handler/http.rs"
click node_ws_handler "https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/handler/websocket.rs"
click node_ui_state "https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/state.rs"
click node_ui_signal "https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/signal.rs"
click node_connect_uc "https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/connect_participant.rs"
click node_disconnect_uc "https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/disconnect_participant.rs"
click node_send_uc "https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/send_message.rs"
click node_rooms_uc "https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/get_rooms.rs"
click node_domain_core "https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/mod.rs"
click node_repo_contract "https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/repository.rs"
click node_pusher_contract "https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/message_pusher.rs"
click node_infra_repo "https://github.com/nukopy/engawa/blob/main/packages/server/src/infrastructure/repository/mod.rs"
click node_infra_pusher "https://github.com/nukopy/engawa/blob/main/packages/server/src/infrastructure/message_pusher/websocket.rs"
click node_dto_map "https://github.com/nukopy/engawa/blob/main/packages/server/src/infrastructure/dto/conversion.rs"
click node_client_bin "https://github.com/nukopy/engawa/blob/main/packages/client/src/bin/client.rs"
click node_runner "https://github.com/nukopy/engawa/blob/main/packages/client/src/runner.rs"
click node_session "https://github.com/nukopy/engawa/blob/main/packages/client/src/session.rs"
click node_tui "https://github.com/nukopy/engawa/blob/main/packages/client/src/ui.rs"
click node_formatter "https://github.com/nukopy/engawa/blob/main/packages/client/src/formatter.rs"
click node_shared_utils "https://github.com/nukopy/engawa/blob/main/packages/shared/src/lib.rs"
click node_tests_http "https://github.com/nukopy/engawa/blob/main/tests/http_api.rs"
click node_tests_ws_conn "https://github.com/nukopy/engawa/blob/main/tests/websocket_connection.rs"
click node_tests_ws_msg "https://github.com/nukopy/engawa/blob/main/tests/websocket_messaging.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_bin,node_ui_server,node_http_handler,node_ws_handler,node_ui_state,node_ui_signal,node_connect_uc,node_disconnect_uc,node_send_uc,node_rooms_uc,node_domain_core,node_repo_contract,node_pusher_contract,node_infra_repo,node_infra_pusher,node_dto_map toneAmber
class node_client_bin,node_runner,node_session,node_tui,node_formatter toneMint
class node_shared_utils toneRose
class node_tests_http,node_tests_ws_conn,node_tests_ws_msg toneIndigo
```

## Components

### Server app

WebSocket chat service with layered architecture

- [Server entry](https://github.com/nukopy/engawa/blob/main/packages/server/src/bin/server.rs): binary · Starts the chat server process · `packages/server/src/bin/server.rs`
- [Server UI](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/server.rs): adapter · Wires server runtime and request handling · `packages/server/src/ui/server.rs`
- [HTTP handler](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/handler/http.rs): transport handler · Handles HTTP endpoints and connection setup · `packages/server/src/ui/handler/http.rs`
- [WebSocket handler](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/handler/websocket.rs): transport handler · Handles WebSocket upgrades and message exchange · `packages/server/src/ui/handler/websocket.rs`
- [UI state](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/state.rs): runtime state · Holds shared server runtime state · `packages/server/src/ui/state.rs`
- [Shutdown signal](https://github.com/nukopy/engawa/blob/main/packages/server/src/ui/signal.rs): lifecycle · Coordinates server shutdown and termination · `packages/server/src/ui/signal.rs`
- [Connect](https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/connect_participant.rs): use case · Registers a participant and starts a room session · `packages/server/src/usecase/connect_participant.rs`
- [Disconnect](https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/disconnect_participant.rs): use case · Ends a participant session and updates room state · `packages/server/src/usecase/disconnect_participant.rs`
- [Send message](https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/send_message.rs): use case · Coordinates chat message delivery and broadcast · `packages/server/src/usecase/send_message.rs`
- [Room queries](https://github.com/nukopy/engawa/blob/main/packages/server/src/usecase/get_rooms.rs): use case · Fetches rooms, room detail, and room state · `packages/server/src/usecase/get_rooms.rs`
- [Domain model](https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/mod.rs): domain · Entities, value objects, factory, and errors · `packages/server/src/domain/mod.rs`
- [Repository contract](https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/repository.rs): domain port · Persistence abstraction for room and participant state · `packages/server/src/domain/repository.rs`
- [Message pusher](https://github.com/nukopy/engawa/blob/main/packages/server/src/domain/message_pusher.rs): domain port · Abstracts outbound chat event delivery · `packages/server/src/domain/message_pusher.rs`
- [Repos](https://github.com/nukopy/engawa/blob/main/packages/server/src/infrastructure/repository/mod.rs): infrastructure · In-memory and PostgreSQL repository implementations · `packages/server/src/infrastructure/repository/mod.rs`
- [WS pusher](https://github.com/nukopy/engawa/blob/main/packages/server/src/infrastructure/message_pusher/websocket.rs): infrastructure · WebSocket message delivery implementation · `packages/server/src/infrastructure/message_pusher/websocket.rs`
- [DTO mapping](https://github.com/nukopy/engawa/blob/main/packages/server/src/infrastructure/dto/conversion.rs): infrastructure · Converts between domain objects and wire formats · `packages/server/src/infrastructure/dto/conversion.rs`

### Client CLI

Interactive terminal chat client

- [Client entry](https://github.com/nukopy/engawa/blob/main/packages/client/src/bin/client.rs): binary · Starts the CLI chat client · `packages/client/src/bin/client.rs`
- [Runner](https://github.com/nukopy/engawa/blob/main/packages/client/src/runner.rs): orchestrator · Coordinates client startup and reconnect loop · `packages/client/src/runner.rs`
- [Session](https://github.com/nukopy/engawa/blob/main/packages/client/src/session.rs): connection lifecycle · Manages server connection and session state · `packages/client/src/session.rs`
- [Terminal UI](https://github.com/nukopy/engawa/blob/main/packages/client/src/ui.rs): presentation · Handles interactive terminal input and output · `packages/client/src/ui.rs`
- [Formatter](https://github.com/nukopy/engawa/blob/main/packages/client/src/formatter.rs): presentation · Renders incoming chat events for the CLI · `packages/client/src/formatter.rs`

### Shared utils

Cross-cutting runtime helpers

- [Shared core](https://github.com/nukopy/engawa/blob/main/packages/shared/src/lib.rs): utilities · Common logging and time helpers · `packages/shared/src/lib.rs`

### Integration tests

Workspace-level protocol and transport tests

- [HTTP tests](https://github.com/nukopy/engawa/blob/main/tests/http_api.rs): integration test · Validates HTTP and server connection behavior · `tests/http_api.rs`
- [WS connect](https://github.com/nukopy/engawa/blob/main/tests/websocket_connection.rs): integration test · Validates WebSocket connection lifecycle · `tests/websocket_connection.rs`
- [WS messaging](https://github.com/nukopy/engawa/blob/main/tests/websocket_messaging.rs): integration test · Validates room broadcasts and chat delivery · `tests/websocket_messaging.rs`

## Connections

- Server entry → Server UI: starts · Binary initializes server runtime
- Server UI → HTTP handler: routes · HTTP requests enter through the UI adapter
- Server UI → WebSocket handler: routes · WebSocket traffic enters through the UI adapter
- Server UI → UI state: shares · Handlers coordinate through shared runtime state
- Server UI → Shutdown signal: stops · Shutdown signal terminates server lifecycle
- HTTP handler → Connect: calls · Connection setup maps to participant connect use case
- HTTP handler → Room queries: calls · Status and room endpoints query application state
- WebSocket handler → Connect: calls · Upgrade and join flow registers a participant
- WebSocket handler → Send message: calls · Incoming chat messages trigger send use case
- WebSocket handler → Disconnect: calls · Disconnect and close events terminate participation
- Connect → Domain model: uses · Use cases operate on domain entities and rules
- Disconnect → Domain model: uses · Use cases operate on domain entities and rules
- Send message → Domain model: uses · Use cases operate on domain entities and rules
- Room queries → Domain model: uses · Queries read domain state and room models
- Domain model → Repository contract: depends on · Domain state is persisted through an abstract repository
- Domain model → Message pusher: depends on · Chat events are emitted through an abstract pusher
- Repository contract → Repos: implemented by · Concrete storage backends satisfy repository contract
- Message pusher → WS pusher: implemented by · WebSocket delivery satisfies outbound event contract
- Repos → DTO mapping: uses · Infrastructure maps between persistence and domain/transport shapes
- WS pusher → DTO mapping: uses · Outbound messages are serialized through DTO mapping
- Client entry → Runner: starts · CLI binary hands control to runner
- Runner → Session: manages · Runner owns connection lifecycle and reconnect behavior
- Runner → Terminal UI: drives · Runner coordinates terminal interaction
- Session → Formatter: feeds · Incoming events are prepared for display
- Session → Terminal UI: updates · Session state is reflected in the terminal UI
- Shared core → Server entry: used by · Server runtime shares logging/time helpers
- Shared core → Client entry: used by · Client runtime shares logging/time helpers
- HTTP tests → HTTP handler: verifies · Integration tests cover HTTP behavior
- WS connect → WebSocket handler: verifies · Integration tests cover WebSocket connection behavior
- WS messaging → Send message: verifies · Integration tests cover chat broadcast behavior
