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!**