@@ -0,0 +1,91 @@
# 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.**
esco created this gist