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

---

🎯 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

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

---

📋 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

---

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