How tk-codes/uno works
1. Repository purpose and shape
- This is a Java/Gradle desktop application implementing the UNO card game.
- The code is split into a UI layer, a small application service layer, and a domain-driven core. The README explicitly says the GUI exists mainly to exercise the domain logic, not as a production-grade client.
2. Runtime entry point
- UnoApp is the main entry point.
- It boots the desktop application, which then drives the UI and indirectly the game domain. There is no sign of a server, database, or network boundary.
3. UI subsystem
- ui.AppFrame is the top-level window/container.
- ui.view.* contains the visual components for the game table, players, status, cards, and color selection:
- TableView, PlayerView, GameStatusView, CardView, ColorPicker
- ui.common.StyleUtil centralizes appearance/styling.
- The UI is a consumer of application-facing objects, not the source of game rules.
4. Application layer boundary
- application.IGameAppService defines the use-case API for the UI.
- application.GameAppService is the concrete orchestrator between UI actions and the domain model.
- application.dto.PlayerInfoDTO is a UI-facing transfer object, suggesting the application layer shields the UI from direct domain entity exposure.
5. Domain core: game aggregate
- domain.game.Game is the central aggregate root and owns the game state.
- It maintains the active game flow, including:
- players
- draw pile
- discard pile / played cards
- GameBuilder sets up the initial game state and likely enforces valid startup configuration.
- DealerService and DrawPile encapsulate card distribution and drawing mechanics.
6. Game rules and turn logic
- domain.game.CardRules contains the rule checks for whether a card can be played and what effects it has.
- domain.player.PlayerRoundIterator and domain.player.Direction manage turn order and direction changes, which is important for reverse/skip behavior.
- These pieces form the game-flow engine beneath the UI.
7. Cards as immutable value objects
- The card model is a dedicated subsystem under domain.card.
- Card is the base abstraction, with specialized types:
- NumberCard
- ActionCard
- WildCard
- Supporting types include CardColor, CardType, CardDeck, and CardUtil.
- The README notes cards are immutable value objects; wild cards become colored by creating a new value object with the chosen color.
8. Player model
- domain.player.Player is an entity that owns a mutable hand of cards.
- HandCardList models the player’s hand.
- ImmutablePlayer appears to provide a read-only view for consumers such as UI or iteration logic.
- This keeps player identity/entity concerns separate from card-value semantics.
9. Domain events and reactive hooks
- The domain has a lightweight event mechanism under domain.common:
- DomainEvent
- DomainEventPublisher
- DomainEventSubscriber
- The Game aggregate emits events in domain.game.events:
- CardDrawn
- CardPlayed
- GameOver
- This lets side effects be handled outside the aggregate while keeping core rules isolated.
10. Main data flow
- User interaction starts in the UI.
- The UI calls the application service (GameAppService via IGameAppService).
- The application service invokes the domain aggregate (Game) and supporting domain services.
- The domain updates state and publishes domain events.
- UI-facing components then reflect the updated state, likely using DTOs/read-only views rather than mutating the domain directly.
11. Architectural boundaries
- The important boundaries are:
- UI vs application: presentation does not contain rules
- application vs domain: orchestration is separated from business logic
- entity/value object split: players are entities; cards are immutable values
- aggregate/event boundary: Game owns consistency and publishes events for external reactions
- This is a clean DDD-style boundary structure, with the game aggregate as the main consistency boundary.
12. Testing and quality tooling
- Tests are organized to mirror the domain structure under src/test/java/domain/....
- There are focused tests for cards, rules, deck, draw pile, builder, gameplay, iterator behavior, and event publishing.
- The repo uses Gradle with a wrapper, plus GitHub Actions workflows for tests and Sonar analysis.
- log4j2.xml indicates logging is configured, but logging is not a major architectural component.
13. What to draw in an architecture diagram
- Draw a three-layer flow: UI → Application Service → Domain Aggregate/Services.
- Inside the domain, show three main clusters:
- Cards
- Players
- Game/Rules/Events
- Add arrows from Game to DomainEventPublisher and then to event subscribers.
- Keep everything contained in a single desktop application boundary; there are no external data stores or backend services visible in this repository.
Main entry points: Game.java Game · Card.java Card · AppFrame.java App Frame · GameAppService.java Game App Service
Components 34
UI
Desktop presentation layer
- App Frame · Top-level window and UI container
src/main/java/ui/AppFrame.java - Table View · Main game table presentation
src/main/java/ui/view/TableView.java - Player View · Player hand and identity view
src/main/java/ui/view/PlayerView.java - Status View · Game state and turn status
src/main/java/ui/view/GameStatusView.java - Card View · Card rendering component
src/main/java/ui/view/CardView.java - Color Picker · Wild card color selection
src/main/java/ui/view/ColorPicker.java - Style Util · Shared presentation styling
src/main/java/ui/common/StyleUtil.java
Application
Use-case orchestration layer
- IGameAppService · UI-facing game use-case contract
src/main/java/application/IGameAppService.java - Game App Service · Orchestrates UI actions into domain calls
src/main/java/application/GameAppService.java - Player Info · UI-facing player transfer object
src/main/java/application/dto/PlayerInfoDTO.java
Cards
Immutable card model subsystem
- Card · Base immutable card abstraction
src/main/java/domain/card/Card.java - Number Card · Numeric card variant
src/main/java/domain/card/NumberCard.java - Action Card · Skip/reverse/draw action card
src/main/java/domain/card/ActionCard.java - Wild Card · Color-selectable wild card
src/main/java/domain/card/WildCard.java - Card Deck · Deck construction and composition
src/main/java/domain/card/CardDeck.java - Card Util · Card-related helpers and conversions
src/main/java/domain/card/CardUtil.java - Card Color · Card color domain type
src/main/java/domain/card/CardColor.java - Card Type · Card kind domain type
src/main/java/domain/card/CardType.java
Players
Player entity and turn mechanics
- Player · Player entity with mutable hand
src/main/java/domain/player/Player.java - Hand Cards · Player hand model
src/main/java/domain/player/HandCardList.java - Immutable Player · Read-only player view
src/main/java/domain/player/ImmutablePlayer.java - Round Iterator · Turn sequencing and current player iteration
src/main/java/domain/player/PlayerRoundIterator.java - Direction · Forward and reverse turn direction
src/main/java/domain/player/Direction.java
Game
Aggregate, setup, and rule flow
- Game · Central game state and consistency boundary
src/main/java/domain/game/Game.java - Game Builder · Initial game construction and validation
src/main/java/domain/game/GameBuilder.java - Card Rules · Playable-card and effect logic
src/main/java/domain/game/CardRules.java - Dealer Service · Card dealing mechanics
src/main/java/domain/game/DealerService.java - Draw Pile · Draw stack and replenishment source
src/main/java/domain/game/DrawPile.java - Card Drawn · Event emitted when a card is drawn
src/main/java/domain/game/events/CardDrawn.java - Card Played · Event emitted when a card is played
src/main/java/domain/game/events/CardPlayed.java
Common
Shared domain event abstractions
- Domain Event · Base domain event contract
src/main/java/domain/common/DomainEvent.java - Event Publisher · Publishes domain events
src/main/java/domain/common/DomainEventPublisher.java - Event Subscriber · Consumes domain events
src/main/java/domain/common/DomainEventSubscriber.java
Other components
- UnoApp · Desktop application entry point
src/main/java/UnoApp.java
Connections 39
- UnoApp → App Frame: starts · Bootstraps the desktop UI
- App Frame → IGameAppService: uses · UI delegates actions through the service port
- IGameAppService → Game App Service: implemented by · Concrete application orchestration
- Game App Service → Game Builder: initializes · Creates or configures a game session
- Game App Service → Game: drives · Invokes domain operations
- Game App Service → Player Info: returns · Exposes read-friendly player data to the UI
- Game App Service → Immutable Player: reads · Uses read-only player projections
- App Frame → Table View: contains · Composes the main table view
- App Frame → Player View: contains · Composes player panels
- App Frame → Status View: contains · Composes game status area
- Table View → Card View: renders · Displays cards in play
- Table View → Color Picker: prompts · Requests wild card color choice
- Player View → Card View: renders · Shows player hand cards
- App Frame → Style Util: styles · Shares UI appearance rules
- Game Builder → Card Deck: builds from · Assembles the starting deck
- Game Builder → Draw Pile: creates · Initializes draw pile state
- Game Builder → Player: creates · Creates players for the match
- Game → Card Rules: applies · Checks legality and card effects
- Game → Dealer Service: uses · Deals cards and manages distribution
- Game → Draw Pile: owns · Maintains draw pile consistency
- Game → Player: owns · Maintains player state
- Game → Round Iterator: advances · Coordinates turn order
- Round Iterator → Direction: tracks · Supports reverse and forward flow
- Player → Hand Cards: contains · Player hand aggregate part
- Player → Immutable Player: exposes · Provides read-only view for consumers
- Card → Number Card: specializes · Numeric card variant
- Card → Action Card: specializes · Action card variant
- Card → Wild Card: specializes · Wild card variant
- Card Deck → Card: composes · Deck is made of cards
- Card → Card Color: uses · Cards carry color state
- Card → Card Type: uses · Cards carry type state
- Card Util → Card: helps · Card creation and manipulation helpers
- Game → Event Publisher: publishes via · Emits state-change events
- Event Publisher → Domain Event: publishes · Dispatches domain events
- Event Publisher → Event Subscriber: notifies · Fan-out to subscribers
- Card Drawn → Domain Event: implements · Game-specific event type
- Card Played → Domain Event: implements · Game-specific event type
- Game → Card Drawn: emits · Signals draw actions
- Game → Card Played: emits · Signals play actions