chess/docs/STRUCTURE_DECISION_TREE.md

Repository Structure Decision Tree

Quick reference guide for making structure decisions as the project evolves.

---

When to Consider Restructuring

Use this decision tree when you encounter structure questions:

START: Should we change the directory structure?
│
├─► Are we adding a build step? (TypeScript, Webpack, Vite, etc.)
│   │
│   ├─► YES → Consider `/src/` + `/dist/` structure
│   │         Benefits: Source vs. compiled separation
│   │         Cost: Migration effort (15-20 hours)
│   │         Recommended: Only if build is necessary
│   │
│   └─► NO → Keep current structure ✅
│
├─► Is the project becoming a monorepo? (multiple packages)
│   │
│   ├─► YES → Consider `/packages/` structure
│   │         Benefits: Multiple publishable packages
│   │         Cost: High (new tooling, CI/CD changes)
│   │         Recommended: Only with 3+ independent packages
│   │
│   └─► NO → Keep current structure ✅
│
├─► Are imports becoming complex? (../../../components/...)
│   │
│   ├─► YES → Fix imports, DON'T restructure
│   │         Solution: Use path aliases in jsconfig.json
│   │         Example: "@/pieces" instead of "../../pieces"
│   │
│   └─► NO → Keep current structure ✅
│
├─► Is a directory growing too large? (>20 files)
│   │
│   ├─► YES → Create logical subdirectories WITHIN that directory
│   │         Example: /js/pieces/ → /js/pieces/standard/ + /js/pieces/variants/
│   │         DON'T: Move entire directory structure
│   │
│   └─► NO → Keep current structure ✅
│
├─► Are we converting to a library/package?
│   │
│   ├─► YES → Consider `/lib/` or `/dist/` for publishable code
│   │         Benefits: Clear library entry point
│   │         Cost: Medium (package.json updates, build config)
│   │
│   └─► NO → Keep current structure ✅
│
└─► Is this purely aesthetic or "feeling wrong"?
    │
    ├─► YES → DON'T change ⛔
    │         Rationale: Current structure follows best practices
    │         Risk: Unnecessary churn, broken imports, CI/CD updates
    │
    └─► NO → Evaluate with technical criteria above

---

Adding Features Decision Tree

START: Where should I add this new feature?
│
├─► Is it a new chess piece type?
│   └─► Add to /js/pieces/
│       Example: /js/pieces/Archbishop.js (chess variant)
│
├─► Is it a new game rule or validation?
│   └─► Add to /js/engine/
│       Example: /js/engine/DrawConditions.js
│
├─► Is it a new UI component?
│   ├─► Rendering logic? → /js/views/
│   │   Example: /js/views/ThemeRenderer.js
│   │
│   └─► User interaction? → /js/controllers/
│       Example: /js/controllers/TouchHandler.js
│
├─► Is it a major new feature domain? (AI, Network, Puzzles)
│   └─► Create new top-level directory in /js/
│       Examples:
│       - /js/ai/ (AI opponent)
│       - /js/network/ (Multiplayer)
│       - /js/puzzles/ (Puzzle mode)
│       - /js/analysis/ (Game analysis)
│
├─► Is it a utility function?
│   └─► Add to /js/utils/
│       Example: /js/utils/FENParser.js
│
├─► Is it a new stylesheet?
│   └─► Add to /css/
│       Example: /css/themes.css, /css/animations.css
│
├─► Is it test-related?
│   └─► Mirror source structure in /tests/
│       Example: /js/ai/MinimaxEngine.js → /tests/unit/ai/MinimaxEngine.test.js
│
└─► Is it documentation?
    └─► Add to /docs/
        Example: /docs/AI_DESIGN.md

---

File Size Guidelines

File Size Thresholds:
─────────────────────────────────────────────────

< 300 lines     ✅ Optimal size
300-500 lines   ⚠️  Consider refactoring soon
500-800 lines   🔴 Should refactor into modules
> 800 lines     ⛔ MUST refactor immediately

Action when file is too large:
1. Extract related functions into new files
2. Create subdirectory if needed
3. Update imports
4. Update tests

---

Directory Size Guidelines

Files per Directory:
─────────────────────────────────────────────────

1-7 files       ✅ Optimal (easy to scan)
8-15 files      ⚠️  Still manageable
16-25 files     🔴 Consider grouping into subdirectories
> 25 files      ⛔ MUST create subdirectories

Action when directory is too large:
1. Group related files logically
2. Create subdirectories by feature/concern
3. Maintain flat structure where possible
4. DON'T go deeper than 4 levels

---

Import Path Complexity Guidelines

Relative Import Depth:
─────────────────────────────────────────────────

./file.js           ✅ Same directory (best)
../other.js         ✅ Parent directory (good)
../../file.js       ⚠️  Two levels up (acceptable)
../../../file.js    🔴 Three levels up (refactor structure)
../../../../        ⛔ NEVER acceptable (broken structure)

Solutions for deep imports:
1. Restructure directories to reduce depth
2. Use path aliases (jsconfig.json)
3. Create barrel exports (index.js files)

---

When to Use Subdirectories

✅ Create Subdirectory When:

• Grouping related files (≥3 files with same concern)
• Feature domain is distinct (AI, Network, Puzzles)
• Files share common dependencies
• Clear boundary exists (pieces/standard vs. pieces/variants)

❌ DON'T Create Subdirectory When:

• Only 1-2 files would be in it
• No clear logical grouping
• Just to reduce directory size aesthetically
• It would increase import complexity

---

Migration Checklist

If you MUST restructure (e.g., adding TypeScript), follow this checklist:

Phase 1: Planning (Day 1)

• Document current import paths
• List all files to be moved
• Identify CI/CD dependencies
• Review HTML script tags
• Check web server configurations
• Backup current state (git tag)

Phase 2: Code Changes (Day 2-3)

• Create new directory structure
• Move files with git mv (preserves history)
• Update ALL import paths
• Update HTML script tags
• Update package.json scripts
• Update jsconfig.json / tsconfig.json

Phase 3: Infrastructure (Day 4)

• Update CI/CD workflows (.gitea/workflows/*.yml)
• Update linter configuration
• Update test configurations
• Update .gitignore if needed
• Update web server configs

Phase 4: Documentation (Day 5)

• Update README.md examples
• Update all /docs/ file references
• Update API documentation
• Create migration notes
• Update CLAUDE.md instructions

Phase 5: Testing (Day 6-7)

• Run full test suite
• Verify CI/CD pipeline
• Test local development server
• Test production build
• Test all import paths
• Manual QA testing

Phase 6: Deployment

• Create pull request
• Team review
• Merge and deploy
• Monitor for issues
• Update team documentation

Estimated Effort: 15-20 hours minimum Risk Level: High Only proceed if benefits clearly outweigh costs!

---

Common Scenarios & Decisions

Scenario 1: "We want to add TypeScript"

Question: Should we restructure?
Answer: YES - Create /src/ and /dist/

New Structure:
chess-game/
├── src/                  ← TypeScript source
│   ├── js/              (rename to /ts/)
│   ├── css/
│   └── index.html
├── dist/                ← Compiled JavaScript
└── tsconfig.json

Rationale: Build step justifies source/output separation
Effort: 15-20 hours

---

Scenario 2: "We want to add Vite bundler"

Question: Should we restructure?
Answer: MAYBE - Vite works with current structure

Option A: Keep current (easier)
- Vite serves from root
- vite.config.js points to index.html
- No migration needed

Option B: Move to /src/ (standard Vite pattern)
- Follows Vite conventions
- Requires migration effort

Recommendation: Start with Option A, migrate to B only if needed

---

Scenario 3: "The /js/pieces/ directory has 20 files"

Question: Should we restructure entire project?
Answer: NO - Restructure ONLY /js/pieces/

Solution:
js/pieces/
├── standard/           ← FIDE pieces
│   ├── Pawn.js
│   ├── Knight.js, etc.
├── variants/           ← Chess variants
│   ├── Archbishop.js
│   └── Chancellor.js
└── Piece.js           ← Base class stays at top

Impact: Minimal (only pieces/ imports change)
Effort: 2-3 hours

---

Scenario 4: "Imports are getting messy"

Question: Should we restructure?
Answer: NO - Use path aliases

Solution: Create jsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/pieces/*": ["js/pieces/*"],
      "@/engine/*": ["js/engine/*"],
      "@/utils/*": ["js/utils/*"]
    }
  }
}

Before: import { Piece } from '../../pieces/Piece.js';
After:  import { Piece } from '@/pieces/Piece.js';

Impact: None (aliases only)
Effort: 1 hour

---

Scenario 5: "We're building a mobile app too"

Question: Should we restructure to monorepo?
Answer: MAYBE - Depends on code sharing

Option A: Separate repos (if little code sharing)
chess-game/           (web)
chess-game-mobile/    (mobile)

Option B: Monorepo (if significant code sharing)
chess-project/
├── packages/
│   ├── web/          (current project)
│   ├── mobile/       (React Native)
│   └── shared/       (chess engine, shared logic)

Recommendation: Start with Option A, move to B only if needed

---

Red Flags: When NOT to Restructure

🚩 Don't restructure if:

• "It just feels wrong" (aesthetic preference)
• "Other projects do it differently" (context matters)
• "We might need it someday" (YAGNI principle)
• "I read an article about /src/" (blindly following trends)
• "The folder has too many files" (create subdirectories, don't restructure all)

✅ Do restructure if:

• Adding build/compilation step (TypeScript, bundling)
• Converting to monorepo (multiple packages)
• Technical constraint requires it (framework convention)
• Import complexity is unmanageable (>3 levels)
• Team consensus with clear technical benefit

---

Quick Reference: Project Type → Structure

Project Type	Structure	Rationale
Vanilla JS Web App	Root-level /js/, /css/	✅ Current (optimal)
TypeScript Project	/src/ + /dist/	Build step justifies separation
React/Vue/Angular	/src/	Framework convention
Library/Package	/lib/ or /dist/	Publishable output
Monorepo	/packages/	Multiple independent packages
Static Site	Root-level files	Direct web serving

Our Project: Vanilla JS Web App → Current structure is correct ✅

---

Summary: Golden Rules

1. YAGNI Principle: Don't restructure until you actually need it
2. Flat is Better: Avoid unnecessary nesting
3. Convention > Configuration: Follow standards for your project type
4. Measure Twice, Cut Once: Restructuring is expensive
5. Technical Justification: Need clear technical benefit, not just aesthetics
6. Team Agreement: Get consensus before major changes
7. Migration Plan: Never restructure without a detailed plan
8. Test Everything: Structure changes break things subtly

---

Last Updated: November 23, 2025 Use this guide for all future structure decisions!