juanatsap
69012bb1ae
New test files: - config/config_test.go (100% coverage) - constants/constants_test.go (100% coverage) - httputil/response_test.go (100% coverage) - validation/rules_test.go (91.9% coverage) - middleware/logger_test.go, security_test.go, security_logger_test.go - handlers/errors_test.go Updated documentation: - doc/27-GO-TESTING.md: Complete testing guide - doc/00-GO-DOCUMENTATION-INDEX.md: Added testing section - doc/01-ARCHITECTURE.md: Updated package structure - doc/DECISIONS.md: Added ADR-004 caching decision - PROJECT-MEMORY.md: Added Go testing section
165 lines
7.2 KiB
Markdown
165 lines
7.2 KiB
Markdown
# CV Project Documentation
|
|
|
|
**Complete documentation for the Go + HTMX CV website project.**
|
|
|
|
---
|
|
|
|
## 📚 Quick Navigation
|
|
|
|
### For Developers
|
|
|
|
**Getting Started**
|
|
- [1. Architecture Overview](1-ARCHITECTURE.md) - System design and Go backend architecture
|
|
- [2. Modern Web Techniques](2-MODERN-WEB-TECHNIQUES.md) - Frontend architecture (HTMX, Hyperscript, CSS) ⭐
|
|
- [3. API Reference](3-API.md) - Complete API documentation with endpoints and responses
|
|
|
|
**Technical Implementation**
|
|
- [4. Hyperscript Rules](4-HYPERSCRIPT-RULES.md) - Hyperscript conventions and best practices
|
|
- [5. Zoom Implementation](5-ZOOM-IMPLEMENTATION.md) - Custom zoom feature technical details
|
|
- [12. CSS Architecture](12-CSS-ARCHITECTURE.md) - Modular CSS structure and ITCSS organization ⭐
|
|
- [13. Toast Notifications](13-TOAST-NOTIFICATIONS.md) - Toast notification system for PDF downloads and user feedback
|
|
- [14. Backend Handlers](14-BACKEND-HANDLERS.md) - Handler architecture, type safety, middleware, and testing ⭐
|
|
- [16. CMD+K API](16-CMD-K-API.md) - Command palette API for ninja-keys integration ⭐
|
|
|
|
**Contact Form & Security**
|
|
- [17. Contact Form](17-CONTACT-FORM.md) - Quick start guide for contact form with SMTP setup
|
|
- [18. Security Audit](18-SECURITY-AUDIT.md) - Comprehensive security audit report (OWASP Top 10)
|
|
- [19. Security Implementation](19-SECURITY-IMPLEMENTATION.md) - Detailed security controls documentation
|
|
|
|
**Testing & Quality**
|
|
- [27. Testing](27-GO-TESTING.md) - Comprehensive testing documentation with coverage analysis
|
|
|
|
**Deployment & Operations**
|
|
- [8. Deployment Guide](8-DEPLOYMENT.md) - Production deployment instructions
|
|
- [9. Security Policies](9-SECURITY.md) - Security guidelines and vulnerability reporting
|
|
|
|
---
|
|
|
|
### For Users & Customizers
|
|
|
|
- [6. User Guide](6-USER-GUIDE.md) - End-user documentation for CV features
|
|
- [7. Customization Guide](7-CUSTOMIZATION.md) - How to customize your CV content and styling
|
|
- [10. Privacy Policy](10-PRIVACY.md) - Data handling and privacy information
|
|
|
|
---
|
|
|
|
## 📖 Documentation Overview
|
|
|
|
### Core Technical Documentation
|
|
|
|
| # | Document | Purpose | Audience |
|
|
|---|----------|---------|----------|
|
|
| 1 | [ARCHITECTURE.md](1-ARCHITECTURE.md) | Go backend architecture, package structure, design patterns | Backend developers |
|
|
| 2 | [MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) | HTMX/Hyperscript frontend architecture, component patterns, ADRs | Frontend developers |
|
|
| 3 | [API.md](3-API.md) | Complete API reference with all endpoints | API consumers, integrators |
|
|
| 4 | [HYPERSCRIPT-RULES.md](4-HYPERSCRIPT-RULES.md) | Hyperscript coding conventions | Frontend developers |
|
|
| 5 | [ZOOM-IMPLEMENTATION.md](5-ZOOM-IMPLEMENTATION.md) | Zoom feature implementation details | Feature developers |
|
|
| 12 | [CSS-ARCHITECTURE.md](12-CSS-ARCHITECTURE.md) | Modular CSS structure, ITCSS layers, HTMX integration | Frontend developers, designers |
|
|
| 13 | [TOAST-NOTIFICATIONS.md](13-TOAST-NOTIFICATIONS.md) | Toast notification system, PDF download feedback, user notifications | Frontend developers, UX designers |
|
|
| 14 | [BACKEND-HANDLERS.md](14-BACKEND-HANDLERS.md) | Handler architecture, type safety, middleware pattern, testing strategy | Backend developers |
|
|
| 15 | [SEO.md](15-SEO.md) | SEO optimization and best practices | Frontend developers |
|
|
| 16 | [CMD-K-API.md](16-CMD-K-API.md) | CMD+K command palette API, ninja-keys integration | Frontend developers |
|
|
| 17 | [CONTACT-FORM.md](17-CONTACT-FORM.md) | Contact form quick start guide | Backend developers |
|
|
| 18 | [SECURITY-AUDIT.md](18-SECURITY-AUDIT.md) | Comprehensive security audit (OWASP Top 10) | Security teams |
|
|
| 19 | [SECURITY-IMPLEMENTATION.md](19-SECURITY-IMPLEMENTATION.md) | Security controls implementation details | Backend developers, Security |
|
|
| 27 | [GO-TESTING.md](27-GO-TESTING.md) | Comprehensive testing documentation and coverage | Backend developers, QA |
|
|
|
|
### User & Operations Documentation
|
|
|
|
| # | Document | Purpose | Audience |
|
|
|---|----------|---------|----------|
|
|
| 6 | [USER_GUIDE.md](6-USER-GUIDE.md) | End-user feature documentation | CV users |
|
|
| 7 | [CUSTOMIZATION.md](7-CUSTOMIZATION.md) | Content and style customization | CV customizers |
|
|
| 8 | [DEPLOYMENT.md](8-DEPLOYMENT.md) | Deployment instructions and operations | DevOps, site operators |
|
|
| 9 | [SECURITY.md](9-SECURITY.md) | Security policies and reporting | Security teams |
|
|
| 10 | [PRIVACY.md](10-PRIVACY.md) | Privacy policy and data handling | Legal, compliance |
|
|
| 11 | [PDF-EXPORT.md](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](1-ARCHITECTURE.md) (backend) and [2-MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) (frontend)
|
|
|
|
**...add a new feature**
|
|
→ Read [2-MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) for frontend patterns, [3-API.md](3-API.md) for backend APIs
|
|
|
|
**...customize my CV content**
|
|
→ Follow [7-CUSTOMIZATION.md](7-CUSTOMIZATION.md) for content and styling changes
|
|
|
|
**...deploy to production**
|
|
→ Use [8-DEPLOYMENT.md](8-DEPLOYMENT.md) for step-by-step deployment instructions
|
|
|
|
**...understand HTMX patterns**
|
|
→ Check [2-MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) Section 6 (HTMX Patterns)
|
|
|
|
**...write Hyperscript code**
|
|
→ Follow conventions in [4-HYPERSCRIPT-RULES.md](4-HYPERSCRIPT-RULES.md)
|
|
|
|
**...report a security issue**
|
|
→ See [9-SECURITY.md](9-SECURITY.md) for responsible disclosure process
|
|
|
|
**...understand or improve test coverage**
|
|
→ Read [27-GO-TESTING.md](27-GO-TESTING.md) for coverage analysis and testing patterns
|
|
|
|
---
|
|
|
|
## 📦 Archive
|
|
|
|
Historical documentation (bug fixes, testing reports, implementation notes) is stored in [`archive/`](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-12-06
|
|
**Documentation Status**: Organized, comprehensive
|
|
**Total Active Docs**: 20 core documents + archive
|