juanatsap
9a848e8c53
Implement a command palette accessible via CMD+K/Ctrl+K using the ninja-keys web component. Features include: - New /api/cmd-k endpoint serving dynamic CV entries (experiences, projects, courses) - Language-aware responses with 1-hour cache headers - Scroll-to-section functionality for quick navigation - Enhanced keyboard shortcuts modal with CMD+K documentation - Comprehensive test coverage for API and UI interactions Also includes cleanup of deprecated debug test files and various UI polish improvements to contact form, themes, and action bar components.
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