bookhoard/PROJECT_GUIDELINES.md

# Combined Project Guidelines for Bookmann

## 🚨 CRITICAL PROHIBITIONS (Never violate these)

### Backend & Database
- ❌ **NEVER modify backend code when working on frontend-only tasks**
- ❌ **NEVER modify database schema** unless explicitly instructed for full-stack changes
- ❌ **NEVER use Docker** - use Podman only
- ❌ **NEVER build server binaries locally** - all builds through Dockerfile/docker-compose
- ❌ **NEVER create new migration files** - merge changes into current one until release
- ❌ **NEVER use `git checkout` on schema files** without checking what will be lost
- ❌ **NEVER break existing functionality** unless explicitly instructed

### Frontend & Styling
- ❌ **NEVER modify backend/API for frontend features without user confirmation**
- ❌ **NEVER use custom CSS** - TailwindCSS classes only
- ❌ **NEVER use JavaScript** - convert all to TypeScript
- ❌ **NEVER use object-oriented programming** patterns - use functional/other paradigms
- ❌ **NEVER add new Dockerfiles without user confirmation**

### General
- ❌ **NEVER skip pre-commit hooks** unless explicitly requested
- ❌ **NEVER force push to main/master** branches
- ❌ **NEVER commit files with secrets** (.env, credentials.json, etc.)
- ❌ **NEVER make assumptions** - ask clarifying questions when uncertain
- ❌ **NEVER delete code without reading full context first** (minimum 20 lines before/after)
- ❌ **NEVER make cascading fix-up edits without git diff review**
  - After compilation error: STOP, review `git diff`, understand full impact
  - Use revert/re-apply pattern instead of blind fixes
- ❌ **NEVER skip post-edit verification** - must compile after each file edit

### Cascading Fix-up Pattern (PROHIBITED)

**WHAT NOT TO DO** - This caused critical bugs:
```go
// ❌ WRONG: Blindly making fixes after compilation error

Edit 1: Delete deprecated code
[Compilation error: undefined Register]

Edit 2: Try to fix error (over-broad deletion)
[More errors: undefined Login, GetProfile, etc.]

Edit 3: Try to fix again (worse damage)
[Even more errors: major functionality broken]
```

**CORRECT APPROACH**:
```go
// ✅ CORRECT: Stop, understand, then fix deliberately

Edit 1: Delete deprecated code
[Compilation error: undefined Register]

STOP → Review git diff → Understand Register was accidentally deleted
RESTORE → Get exact Register function from git history
VERIFY → Compile successfully
```

**Key Principle**: When compilation errors occur after edits:
1. STOP - Don't make more edits
2. ANALYZE - Use `git diff` to understand what was changed
3. RECOVER - Restore what was accidentally deleted/broken
4. VERIFY - Compile and test before proceeding

---

## 🎯 CONTEXT-SPECIFIC RULES

### When Working on Frontend-Only Tasks
- **DO NOT touch backend code** - handlers, services, database layer
- **DO NOT modify API routes** - use existing endpoints only
- **DO NOT change database schema** - work with existing structure
- **If backend change seems necessary**:
  1. Identify the required change
  2. Explain why you need it
  3. Provide impact analysis
  4. **ASK FOR USER CONFIRMATION before proceeding**

### When Working on Full-Stack Tasks
- Backend changes are allowed when explicitly part of the task
- Still follow all database protocols (atomic changes, validation, etc.)
- Still use Podman for all builds
- Still include Bruno tests for API changes

---

## ✅ MANDATORY REQUIREMENTS

### Database Operations (Full-Stack Tasks Only)
- ✅ Follow **pgx v5 standards** for all database operations
- ✅ Treat schema changes as **ATOMIC** - complete success or complete rejection
- ✅ When schema changes occur: delete database and rebuild with clean Podman cache
- ✅ Use **pre-change checklist**: read schema → identify columns → plan changes → verify → read back
- ✅ **Post-change validation**: ensure schema.sql, models.go, and queries.sql are in sync

### Build & Deployment
- ✅ Use **Podman** exclusively (not Docker)
- ✅ All builds through existing **Dockerfile** and **docker-compose.yml**
- ✅ Stop building server binaries - everything goes through containers

### API Changes (Full-Stack Tasks Only)
- ✅ Include **Bruno v3.0 .bru requests** with all API documentation
- ✅ Tests must be **comprehensive and cover three contexts**: no user, user, and admin
- ✅ Maintain backward compatibility for mobile apps and external consumers

### Frontend & Styling
- ✅ Always use **TailwindCSS classes** for all styling
- ✅ Convert all JavaScript to **TypeScript**
- ✅ Avoid OOP patterns - prefer functional/other paradigms

### Code Organization
- ✅ Minimize project structure changes
- ✅ Place new files in **contextually appropriate directories**
- ✅ Follow **KISS**, **DRY**, and **YAGNI** principles
- ✅ Use **multiple, logical git commits** with clear messages

### Configuration & Environment
- ✅ If **.env is missing**, auto-generate secure values
- ✅ Never commit secrets to repository

### Code Modification Safety
- ✅ **Post-Edit Verification (MANDATORY for ALL file modifications)**:
  - Run `go build` for affected packages immediately after each edit
  - Review `git diff filename` to verify only intended changes
  - Validate functionality still works as expected
  - Never proceed to next file until current edit is verified
- ✅ **Backup Before Large Changes**:
  - Create a stash: `git stash push -m "Pre-cleanup snapshot"` before removing >50 lines
  - Or create a backup branch: `git branch backup-before-cleanup`
  - This allows instant recovery if mistakes occur
- ✅ **Large Deletion Safety Pattern**:
  - Read at least 20 lines before/after deletion target
  - Include unique identifiers in match (function signatures, specific comments)
  - Use narrow matches - avoid generic patterns
  - Verify line numbers match intended section

### Documentation
- ✅ Update **README.md** when users/admins need to be informed
- ✅ Document API changes with Bruno collections

### Process & Continuity
- ✅ If mid-task and receive "no response", **continue the task**
- ✅ Verify no regressions before modifying/removing code

---

## 🔧 TECHNICAL STANDARDS

### Backend Stack
- **Language**: Go 1.25+
- **Database**: PostgreSQL 15+ with **pgx v5 driver** only
- **Authentication**: JWT tokens with bcrypt password hashing
- **Architecture**: Service layer pattern (handlers → services → database)

### Frontend Stack
- **Styling**: TailwindCSS (no custom CSS)
- **Language**: TypeScript (no JavaScript)
- **Templates**: HTMX with server-side rendering
- **Patterns**: Functional/other (no OOP)

### Containerization
- **Runtime**: Podman (not Docker)
- **Build**: Existing Dockerfile and docker-compose.yml only
- **No local builds** allowed

---

## 🔄 ERROR RECOVERY PROTOCOL

When code modification mistakes occur (deleted wrong code, broke compilation, etc.):

### Immediate Actions
1. **STOP** - Don't make more edits
2. **ASSESS** - What was deleted? Is it critical?
3. **REVIEW** - Run `git diff` to see exact changes
4. **RESTORE** - Choose appropriate recovery method:
   - **Recent mistake**: `git checkout -- filename`
   - **Complex restoration**: Use `git show HEAD:filename` to recover deleted code
   - **Multiple files**: `git reset HEAD~1` (if safe)
5. **VERIFY** - Compile and test restored code
6. **DOCUMENT** - Note what went wrong for future reference

### Recovery Examples
```bash
# Recover a deleted function from original file
git show HEAD:internal/handlers/auth.go | sed -n '70,275p' > recovery.txt

# Revert entire file to original state
git checkout HEAD -- internal/handlers/auth.go

# Use git stash to save current state before rollback
git stash push -m "Broken state before fix"
git checkout -- internal/handlers/auth.go
```

### Prevention (Learn From Mistakes)
- Why did the mistake happen?
- Was it too-broad matching?
- Was it insufficient context reading?
- Was it cascading fix-up attempts?
- Update guidelines to prevent recurrence

---

## 📋 WORKFLOW CHECKLISTS

### Before Making Frontend-Only Changes
- [ ] Identify if backend modification could make implementation simpler
- [ ] Plan to use existing API endpoints only
- [ ] If backend change seems necessary, prepare confirmation request:
  - Required change description
  - Why it would help
  - Impact analysis
  - Alternative approaches considered
- [ ] Plan git commit structure (multiple logical commits)
- [ ] Identify if README.md needs updates

### Before Making Full-Stack Changes
- [ ] Read current schema completely (if database changes)
- [ ] Identify all columns that must be preserved
- [ ] Plan exact changes needed
- [ ] Verify Podman will be used for builds
- [ ] Plan git commit structure (multiple logical commits)

### During Schema Changes (Full-Stack Only)
- [ ] Read current schema completely
- [ ] Identify all columns that must be preserved
- [ ] Plan exact changes needed
- [ ] Set up verification step
- [ ] Make intended changes
- [ ] Immediately verify by reading back modified sections
- [ ] Confirm ALL expected columns are present
- [ ] Verify schema.sql, models.go, and queries.sql are in sync

### After API Changes
- [ ] Create/update Bruno v3.0 .bru requests
- [ ] Test with no user context
- [ ] Test with regular user context
- [ ] Test with admin context
- [ ] Verify backward compatibility

### Before Committing
- [ ] Run tests: `go test ./... -v`
- [ ] Run lint/typecheck if available
- [ ] Ensure no secrets in changes
- [ ] Verify logical commit structure
- [ ] Update README.md if user-facing changes

### Error Recovery Protocol (If Code Mistakes Occur)
- [ ] **Stop immediately** - don't make more edits
- [ ] **Assess impact**: What was deleted? Is it critical?
- [ ] **Review git diff**: See exact changes made
- [ ] **Restore strategy**:
  - If recent mistake: `git checkout -- filename`
  - If complex: Reconstruct from git diff using `git show HEAD:filename`
- [ ] **Verify recovery**: Compile and test restored code
- [ ] **Document mistake**: Note what went wrong for future reference

### Phase Completion Verification (Before Declaring "Complete")
- [ ] All target code is removed/intact as intended
- [ ] No unintended code was deleted
- [ ] All affected files compile successfully
- [ ] Run `go build ./...` for entire project
- [ ] No critical functionality was broken
- [ ] Git diff shows only intended changes
- [ ] Review all modified files with `git diff --stat`

---

## 🏗 ARCHITECTURAL PATTERNS

### Current: API-Driven Frontend
```
Browser → Go template (empty) → JavaScript fetch() → API → Database
```

### Future Reference: Hybrid SSR (NOT TO IMPLEMENT YET)
```
Browser → Go template (with data) → Display instantly
                    ↓
         JavaScript only for interactivity (CRUD)
                    ↓
              Shared service layer
```

Ultimately, whenever you are unsure just ask for confirmation.