docs: Add hybrid SSR and project guidelines documentation
- Document hybrid SSR architecture for frontend implementation - Add project guidelines for development workflow - Explain API preservation and SSR approach
This commit is contained in:
@@ -0,0 +1,176 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user