# System Prompt: Architectural Principles to Code By

Use rg tool to search for files efficiently 

## Core Principles

1. **Clean, Simple, Maintainable Code**
   - Favor readability over cleverness
   - Prioritize simplicity in design
   - Write code that future developers can easily understand
   - Follow established patterns within the codebase

2. **React Paradigm Compliance**
   - Use functional components with hooks
   - Maintain unidirectional data flow
   - Treat components as pure renderers of state
   - Minimize side effects in rendering logic
   - Separate UI concerns from business logic

3. **No Hacky Fixes**
   - Avoid workarounds that bypass the architecture
   - Don't use DOM manipulation where React state should be used
   - No direct DOM access except in isolated, ref-based scenarios
   - Never use global state outside the established state management system

4. **Thoughtful Change Management**
   - Consider the full impact of every change
   - Document assumptions behind your implementation
   - Write tests that validate your changes
   - Consider large-scale refactoring if it provides better architecture

5. **Logical Decision Making**
	- Be careful and thoughtful with every change
	- Avoid replacing working solutions with inferior alternatives
	- Refrain from making unnecessary changes
	- Focus on improvements that add clear, tangible value
	- Prioritize maintaining and improving overall code quality

## System Architecture Overview

The Yu-Gi-Oh! Web Duel Interface follows a strict separation of concerns:

### Game Engine (Source of Truth)
- Maintains the complete and authoritative game state
- Processes actions through dedicated handlers
- Emits domain events describing game occurrences
- Translates domain events to state patches
- Has no knowledge of UI components or rendering

### UI Layer (Pure Rendering)
- Renders the current game state without modifying it
- Listens for events to trigger animations and UI feedback
- Maintains minimal UI-specific state (animations, menus, etc.)
- Dispatches player actions to the game engine
- Never directly modifies game state

### Communication Pattern
- **Game Engine → UI**: Event-based (domain events, state patches)
- **UI → Game Engine**: Action-based (dispatching typed actions)

## Implementation Guidelines

1. **Domain Events vs. State Patches**
   - Domain events describe WHAT HAPPENED (e.g., `MONSTER_DESTROYED`)
   - State patches describe HOW STATE CHANGED (e.g., `STATE_PATCH`)
   - UI components should process domain events for animations
   - State management should process state patches for updates

2. **When to Consider Refactoring**
   - When new requirements don't fit the current architecture
   - When multiple components need the same hack
   - When state management becomes complex or inconsistent
   - When the separation between engine and UI is compromised

3. **Making Architectural Decisions**
   - Evaluate if the change maintains separation of concerns
   - Consider the long-term maintainability over short-term convenience
   - Check if the solution follows the established event/action pattern
   - Determine if it's an isolated case or represents a systemic issue

## Decision Framework for Changes

When implementing features or fixes, ask yourself:

1. Does this change maintain the separation between game logic and UI?
2. Would a proper domain event solve this problem better than a UI hack?
3. Is this a symptom of a larger architectural issue that should be addressed?
4. Am I introducing state duplication or inconsistency?
5. Would other developers understand my approach without extensive comments?

Remember: **It's better to spend time on a proper architectural solution than to accumulate technical debt through quick fixes.**