docs: restructure documentation and update guidelines
- Update PROJECT_GUIDELINES.md to reflect current architecture (Hybrid SSR) - Integrate service layer and SSR rules into existing sections - Update README.md paths to match new docs structure (docs/developer/api, docs/user/devices) - Remove redundant README.md files from bruno/ directories - Update bruno/collection.bru documentation to current API standard - Fix architectural pattern description from API-driven to Hybrid SSR
This commit is contained in:
+33
-24
@@ -10,6 +10,8 @@
|
||||
- ❌ **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
|
||||
- ❌ **NEVER duplicate business logic** - keep logic in services, not handlers
|
||||
- ❌ **NEVER bypass service layer** - all database operations must go through services
|
||||
|
||||
### Frontend & Styling
|
||||
- ❌ **NEVER modify backend/API for frontend features without user confirmation**
|
||||
@@ -17,6 +19,8 @@
|
||||
- ❌ **NEVER use JavaScript** - convert all to TypeScript
|
||||
- ❌ **NEVER use object-oriented programming patterns in TypeScript** - avoid classes, inheritance, and OOP bloat; use functional/other paradigms
|
||||
- ❌ **NEVER add new Dockerfiles without user confirmation
|
||||
- ❌ **NEVER fetch initial data via AJAX on page load** - use server-side rendering instead
|
||||
- ❌ **NEVER break progressive enhancement** - pages must work without JavaScript
|
||||
|
||||
**Note:** Go methods in the backend are fine and encouraged. This guideline applies to TypeScript/JavaScript frontend code only.**
|
||||
|
||||
@@ -110,6 +114,15 @@ VERIFY → Compile successfully
|
||||
- ✅ Always use **TailwindCSS classes** for all styling
|
||||
- ✅ Convert all JavaScript to **TypeScript**
|
||||
- ✅ Avoid OOP patterns - prefer functional/other paradigms
|
||||
- ✅ **Render initial data server-side** in Go templates for fast page loads
|
||||
- ✅ **Use JavaScript/HTMX for CRUD operations** (create, update, delete)
|
||||
- ✅ **Ensure progressive enhancement** - pages work without JavaScript
|
||||
|
||||
### Service Layer Architecture
|
||||
- ✅ **All business logic in services** - never in handlers
|
||||
- ✅ **Services must be reusable** by both SSR handlers and API endpoints
|
||||
- ✅ **Database operations through services only** - never direct from handlers
|
||||
- ✅ **When adding features**: Add service logic → Create API endpoint → Use SSR for initial render → Use JS for updates
|
||||
|
||||
### Code Organization
|
||||
- ✅ Minimize project structure changes
|
||||
@@ -142,18 +155,19 @@ VERIFY → Compile successfully
|
||||
**Documentation Structure** (updated with full docs system):
|
||||
- ✅ **README.md** - Project overview, quick start, and setup instructions only
|
||||
- ✅ **docs/** - Comprehensive documentation system with search
|
||||
- ✅ **docs/api/** - API reference documentation (split by endpoint/category)
|
||||
- ✅ **docs/devices/** - Device setup guides (KOBO, KOReader, etc.)
|
||||
- ✅ **docs/developer/api/** - API reference documentation (split by endpoint/category)
|
||||
- ✅ **docs/user/** - User-facing features, guides, and workflows
|
||||
- ✅ **docs/user/devices/** - Device setup guides (KOBO, KOReader, etc.)
|
||||
- ✅ **docs/contributing/** - Development and contribution guides
|
||||
|
||||
**Where to document changes**:
|
||||
|
||||
| Change Type | Location | Examples |
|
||||
|-------------|----------|----------|
|
||||
| **User-facing features** | `docs/` or appropriate subdirectory | New features, UI changes, workflows |
|
||||
| **API endpoints** | `docs/api/<category>/<endpoint>.md` | New endpoints, modified responses, authentication changes |
|
||||
| **API behavior** | Update existing `docs/api/` files | Parameter changes, error codes, rate limits |
|
||||
| **Device setup** | `docs/devices/` | New device support, setup instructions |
|
||||
| **User-facing features** | `docs/user/` | New features, UI changes, workflows |
|
||||
| **API endpoints** | `docs/developer/api/<category>/<endpoint>.md` | New endpoints, modified responses, authentication changes |
|
||||
| **API behavior** | Update existing `docs/developer/api/` files | Parameter changes, error codes, rate limits |
|
||||
| **Device setup** | `docs/user/devices/` | New device support, setup instructions |
|
||||
| **Development** | `docs/contributing/` | Build changes, architecture decisions |
|
||||
| **Quick start/setup** | `README.md` | Installation, environment setup, first-run |
|
||||
| **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices |
|
||||
@@ -166,12 +180,12 @@ VERIFY → Compile successfully
|
||||
3. **Update documentation** before or with code changes
|
||||
4. **Verify documentation renders** at `/docs` endpoint
|
||||
5. **Test search** finds new/updated content
|
||||
6. **For API changes**: Update both `docs/api/` files AND Bruno `.bru` files
|
||||
6. **For API changes**: Update both `docs/developer/api/` files AND Bruno `.bru` files
|
||||
7. **Commit separately** with clear message: `docs: <description>`
|
||||
|
||||
**When in doubt**:
|
||||
- End-user visible → `docs/`
|
||||
- API reference → `docs/api/`
|
||||
- End-user visible → `docs/user/`
|
||||
- API reference → `docs/developer/api/`
|
||||
- Setup/onboarding → `README.md`
|
||||
- Development related → `docs/contributing/`
|
||||
|
||||
@@ -251,8 +265,8 @@ git checkout -- internal/handlers/auth.go
|
||||
- Alternative approaches considered
|
||||
- [ ] Plan git commit structure (multiple logical commits)
|
||||
- [ ] **Identify documentation location** (see Documentation section):
|
||||
- [ ] User-facing feature → `docs/`
|
||||
- [ ] UI/workflow changes → `docs/`
|
||||
- [ ] User-facing feature → `docs/user/`
|
||||
- [ ] UI/workflow changes → `docs/user/`
|
||||
- [ ] Setup instructions → `README.md`
|
||||
|
||||
### Before Making Full-Stack Changes
|
||||
@@ -262,9 +276,9 @@ git checkout -- internal/handlers/auth.go
|
||||
- [ ] Verify Podman will be used for builds
|
||||
- [ ] Plan git commit structure (multiple logical commits)
|
||||
- [ ] **Identify documentation location**:
|
||||
- [ ] API changes → `docs/api/<category>/`
|
||||
- [ ] New endpoints → Create new `.md` file in `docs/api/`
|
||||
- [ ] API behavior → Update existing `docs/api/` files
|
||||
- [ ] API changes → `docs/developer/api/<category>/`
|
||||
- [ ] New endpoints → Create new `.md` file in `docs/developer/api/`
|
||||
- [ ] API behavior → Update existing `docs/developer/api/` files
|
||||
- [ ] Breaking changes → Both `README.md` + relevant `docs/`
|
||||
- [ ] Bruno `.bru` files → Update/create alongside API changes
|
||||
|
||||
@@ -291,8 +305,8 @@ git checkout -- internal/handlers/auth.go
|
||||
- [ ] Ensure no secrets in changes
|
||||
- [ ] Verify logical commit structure
|
||||
- [ ] **Update documentation** (see Documentation section):
|
||||
- [ ] User-facing changes → `docs/`
|
||||
- [ ] API changes → `docs/api/` + Bruno `.bru` files
|
||||
- [ ] User-facing changes → `docs/user/`
|
||||
- [ ] API changes → `docs/developer/api/` + Bruno `.bru` files
|
||||
- [ ] Setup/onboarding → `README.md`
|
||||
- [ ] Development changes → `docs/contributing/`
|
||||
- [ ] **Verify docs render** at `/docs` endpoint
|
||||
@@ -321,18 +335,13 @@ git checkout -- internal/handlers/auth.go
|
||||
|
||||
## 🏗 ARCHITECTURAL PATTERNS
|
||||
|
||||
### Current: API-Driven Frontend
|
||||
```
|
||||
Browser → Go template (empty) → JavaScript fetch() → API → Database
|
||||
```
|
||||
|
||||
### Future Reference: Hybrid SSR (NOT TO IMPLEMENT YET)
|
||||
### Current: Hybrid SSR
|
||||
```
|
||||
Browser → Go template (with data) → Display instantly
|
||||
↓
|
||||
JavaScript only for interactivity (CRUD)
|
||||
JavaScript for interactivity (CRUD)
|
||||
↓
|
||||
Shared service layer
|
||||
Shared service layer
|
||||
```
|
||||
|
||||
Ultimately, whenever you are unsure just ask for confirmation.
|
||||
|
||||
Reference in New Issue
Block a user