juanatsap
81e8b3c25e
CLEANUP SUMMARY: - Moved to archive: 3 files (historical/debugging docs) - ZOOM-CONTROL-FIX-REPORT.md - ZOOM-FIXES-COMPLETE-SUMMARY.md - PROJECT_IMPROVEMENT_SUMMARY.md.ASPIRATIONAL → PROJECT_IMPROVEMENT_SUMMARY.md - Deleted: 1 file (duplicate content) - COLOR-THEME-IMPLEMENTATION.md (content already in MODERN-WEB-TECHNIQUES.md) - Created: 1 file (navigation index) - README.md with complete documentation navigation RESULT: - Before: 14 files (403 lines redundant) - After: 11 files (clean, organized, zero redundancy) - Archive: 20 files (properly categorized historical docs) BENEFITS: - Zero documentation duplication - Clear navigation structure - Canonical source for each topic - Historical docs preserved in archive
4.8 KiB
CV Project Documentation
Complete documentation for the Go + HTMX CV website project.
📚 Quick Navigation
For Developers
Getting Started
- Architecture Overview - System design and Go backend architecture
- Modern Web Techniques - Frontend architecture (HTMX, Hyperscript, CSS) ⭐
- API Reference - Complete API documentation with endpoints and responses
Technical Implementation
- Hyperscript Rules - Hyperscript conventions and best practices
- Zoom Implementation - Custom zoom feature technical details
Deployment & Operations
- Deployment Guide - Production deployment instructions
- Security Policies - Security guidelines and vulnerability reporting
For Users & Customizers
- User Guide - End-user documentation for CV features
- Customization Guide - How to customize your CV content and styling
- Privacy Policy - Data handling and privacy information
📖 Documentation Overview
Core Technical Documentation
| Document | Purpose | Audience |
|---|---|---|
| ARCHITECTURE.md | Go backend architecture, package structure, design patterns | Backend developers |
| MODERN-WEB-TECHNIQUES.md | HTMX/Hyperscript frontend architecture, component patterns, ADRs | Frontend developers |
| API.md | Complete API reference with all endpoints | API consumers, integrators |
| ZOOM_IMPLEMENTATION.md | Zoom feature implementation details | Feature developers |
| HYPERSCRIPT-RULES.md | Hyperscript coding conventions | Frontend developers |
User & Operations Documentation
| Document | Purpose | Audience |
|---|---|---|
| USER_GUIDE.md | End-user feature documentation | CV users |
| CUSTOMIZATION.md | Content and style customization | CV customizers |
| DEPLOYMENT.md | Deployment instructions and operations | DevOps, site operators |
| SECURITY.md | Security policies and reporting | Security teams |
| PRIVACY.md | Privacy policy and data handling | Legal, compliance |
🏗️ 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 ARCHITECTURE.md (backend) and MODERN-WEB-TECHNIQUES.md (frontend)
...add a new feature → Read MODERN-WEB-TECHNIQUES.md for frontend patterns, API.md for backend APIs
...customize my CV content → Follow CUSTOMIZATION.md for content and styling changes
...deploy to production → Use DEPLOYMENT.md for step-by-step deployment instructions
...understand HTMX patterns → Check MODERN-WEB-TECHNIQUES.md Section 6 (HTMX Patterns)
...write Hyperscript code → Follow conventions in HYPERSCRIPT-RULES.md
...report a security issue → See 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-18 Documentation Status: ✅ Clean, organized, zero redundancy Total Active Docs: 11 core documents + archive