How nukopy/engawa works
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: mod.rs Domain model · server.rs Server UI · websocket.rs WebSocket handler · http.rs HTTP handler
Components 25
Server app
WebSocket chat service with layered architecture
- Server entry · Starts the chat server process
packages/server/src/bin/server.rs - Server UI · Wires server runtime and request handling
packages/server/src/ui/server.rs - HTTP handler · Handles HTTP endpoints and connection setup
packages/server/src/ui/handler/http.rs - WebSocket handler · Handles WebSocket upgrades and message exchange
packages/server/src/ui/handler/websocket.rs - UI state · Holds shared server runtime state
packages/server/src/ui/state.rs - Shutdown signal · Coordinates server shutdown and termination
packages/server/src/ui/signal.rs - Connect · Registers a participant and starts a room session
packages/server/src/usecase/connect_participant.rs - Disconnect · Ends a participant session and updates room state
packages/server/src/usecase/disconnect_participant.rs - Send message · Coordinates chat message delivery and broadcast
packages/server/src/usecase/send_message.rs - Room queries · Fetches rooms, room detail, and room state
packages/server/src/usecase/get_rooms.rs - Domain model · Entities, value objects, factory, and errors
packages/server/src/domain/mod.rs - Repository contract · Persistence abstraction for room and participant state
packages/server/src/domain/repository.rs - Message pusher · Abstracts outbound chat event delivery
packages/server/src/domain/message_pusher.rs - Repos · In-memory and PostgreSQL repository implementations
packages/server/src/infrastructure/repository/mod.rs - WS pusher · WebSocket message delivery implementation
packages/server/src/infrastructure/message_pusher/websocket.rs - DTO mapping · Converts between domain objects and wire formats
packages/server/src/infrastructure/dto/conversion.rs
Client CLI
Interactive terminal chat client
- Client entry · Starts the CLI chat client
packages/client/src/bin/client.rs - Runner · Coordinates client startup and reconnect loop
packages/client/src/runner.rs - Session · Manages server connection and session state
packages/client/src/session.rs - Terminal UI · Handles interactive terminal input and output
packages/client/src/ui.rs - Formatter · Renders incoming chat events for the CLI
packages/client/src/formatter.rs
Shared utils
Cross-cutting runtime helpers
- Shared core · Common logging and time helpers
packages/shared/src/lib.rs
Integration tests
Workspace-level protocol and transport tests
- HTTP tests · Validates HTTP and server connection behavior
tests/http_api.rs - WS connect · Validates WebSocket connection lifecycle
tests/websocket_connection.rs - WS messaging · Validates room broadcasts and chat delivery
tests/websocket_messaging.rs
Connections 30
- 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