bookhoard/PROJECT_GUIDELINES.md

Combined Project Guidelines for Bookhoard

🚨 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:

// ❌ 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:

// ✅ 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

# 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.