juanatsap
60c1b5ac2b
- Add 6 new utility functions (closeOnBackdrop, scrollToTop, etc.) - Add 10 zoom functions including drag handlers - Document hyperscript reserved words (target, me, it, event) - Add example showing the 'target' parameter pitfall - Update file organization descriptions - Add Phase 2 refactoring details to recent changes
CV Project Documentation
Complete documentation for the Go + HTMX CV website project.
📚 Quick Navigation
For Developers
Getting Started
- 1. Architecture Overview - System design and Go backend architecture
- 2. Modern Web Techniques - Frontend architecture (HTMX, Hyperscript, CSS) ⭐
- 3. API Reference - Complete API documentation with endpoints and responses
Technical Implementation
- 4. Hyperscript Rules - Hyperscript conventions and best practices
- 5. Zoom Implementation - Custom zoom feature technical details
- 12. CSS Architecture - Modular CSS structure and ITCSS organization ⭐
- 13. Toast Notifications - Toast notification system for PDF downloads and user feedback
- 14. Backend Handlers - Handler architecture, type safety, middleware, and testing ⭐
Deployment & Operations
- 8. Deployment Guide - Production deployment instructions
- 9. Security Policies - Security guidelines and vulnerability reporting
For Users & Customizers
- 6. User Guide - End-user documentation for CV features
- 7. Customization Guide - How to customize your CV content and styling
- 10. Privacy Policy - Data handling and privacy information
📖 Documentation Overview
Core Technical Documentation
| # | Document | Purpose | Audience |
|---|---|---|---|
| 1 | ARCHITECTURE.md | Go backend architecture, package structure, design patterns | Backend developers |
| 2 | MODERN-WEB-TECHNIQUES.md | HTMX/Hyperscript frontend architecture, component patterns, ADRs | Frontend developers |
| 3 | API.md | Complete API reference with all endpoints | API consumers, integrators |
| 4 | HYPERSCRIPT-RULES.md | Hyperscript coding conventions | Frontend developers |
| 5 | ZOOM_IMPLEMENTATION.md | Zoom feature implementation details | Feature developers |
| 12 | CSS-ARCHITECTURE.md | Modular CSS structure, ITCSS layers, HTMX integration | Frontend developers, designers |
| 13 | TOAST-NOTIFICATIONS.md | Toast notification system, PDF download feedback, user notifications | Frontend developers, UX designers |
| 14 | BACKEND-HANDLERS.md | Handler architecture, type safety, middleware pattern, testing strategy | Backend developers |
User & Operations Documentation
| # | Document | Purpose | Audience |
|---|---|---|---|
| 6 | USER_GUIDE.md | End-user feature documentation | CV users |
| 7 | CUSTOMIZATION.md | Content and style customization | CV customizers |
| 8 | DEPLOYMENT.md | Deployment instructions and operations | DevOps, site operators |
| 9 | SECURITY.md | Security policies and reporting | Security teams |
| 10 | PRIVACY.md | Privacy policy and data handling | Legal, compliance |
| 11 | PDF-EXPORT.md | PDF generation architecture and configuration | Backend developers |
🏗️ Architecture Quick Reference
Backend: Go (Hono-inspired routing)
- Clean package structure (
internal/pattern) - Template caching and rendering
- JSON-based CV data model
- Middleware: logging, security headers, CORS
Frontend: HTMX + Hyperscript + Vanilla CSS
- Hypermedia-driven architecture (minimal JavaScript)
- Server-side rendering with HTMX partial updates
- Declarative behaviors with Hyperscript
- Component-level skeleton loaders
- Light/dark/auto color themes
Key Features:
- ✅ Custom zoom control (25%-175%)
- ✅ Bilingual support (English/Spanish)
- ✅ Keyboard shortcuts (L/I/V/?)
- ✅ Print-optimized CSS
- ✅ Mobile responsive
- ✅ Accessibility (WCAG AA compliance)
🎯 Common Tasks
"I want to..."
...understand the system architecture → Start with 1-ARCHITECTURE.md (backend) and 2-MODERN-WEB-TECHNIQUES.md (frontend)
...add a new feature → Read 2-MODERN-WEB-TECHNIQUES.md for frontend patterns, 3-API.md for backend APIs
...customize my CV content → Follow 7-CUSTOMIZATION.md for content and styling changes
...deploy to production → Use 8-DEPLOYMENT.md for step-by-step deployment instructions
...understand HTMX patterns → Check 2-MODERN-WEB-TECHNIQUES.md Section 6 (HTMX Patterns)
...write Hyperscript code → Follow conventions in 4-HYPERSCRIPT-RULES.md
...report a security issue → See 9-SECURITY.md for responsible disclosure process
📦 Archive
Historical documentation (bug fixes, testing reports, implementation notes) is stored in archive/ for reference. These documents are not actively maintained but preserved for historical context.
🔗 External Resources
- HTMX Documentation: https://htmx.org/
- Hyperscript: https://hyperscript.org/
- Go Documentation: https://go.dev/doc/
- Playwright Testing: https://playwright.dev/
📝 Documentation Standards
All documentation in this project follows these standards:
- Markdown format with GitHub-flavored syntax
- Clear structure with table of contents for long documents
- Code examples with syntax highlighting
- Up-to-date reflecting current implementation
- Versioned via Git with meaningful commit messages
Last Updated: 2025-11-20 Documentation Status: ✅ Clean, organized, zero redundancy Total Active Docs: 14 core documents + archive