docs: Consolidate documentation into single doc/ folder
- Move docs/ contents to doc/ with proper numbering: - CONTACT-FORM-QUICKSTART.md → 17-CONTACT-FORM.md - SECURITY-AUDIT-REPORT.md → 18-SECURITY-AUDIT.md - SECURITY.md → 19-SECURITY-IMPLEMENTATION.md - Delete duplicate/redundant files from docs/: - CMD-K-COMMAND-BAR.md (duplicate of 16-CMD-K-API.md) - CONTACT_FORM_IMPLEMENTATION.md (overlaps with quickstart) - SECURITY-IMPLEMENTATION-SUMMARY.md (summary of audit) - Update doc/README.md with new document references - Update test counts to 39 test files across all READMEs - Update all "Last Updated" dates to 2025-12-01 - Add new API endpoints documentation (text, cmd-k, contact, toggles) - Update PROJECT-MEMORY.md with new features and correct paths
This commit is contained in:
juanatsap
+198
-4
@@ -200,7 +200,15 @@ This architecture provides:
|
||||
|--------|------|-------------|--------------|------------|
|
||||
| GET | `/` | Full CV page (home) | ❌ No | None |
|
||||
| GET | `/cv` | CV content partial | ✅ Yes | None |
|
||||
| GET | `/text` | Plain text CV for CLI/terminal | ❌ No | None |
|
||||
| GET | `/api/cmd-k` | CMD+K command palette data (JSON) | ❌ No | Cache Control (1h) |
|
||||
| POST | `/api/contact` | Contact form submission | ✅ Yes | BrowserOnly + Rate Limit + CSRF |
|
||||
| GET | `/switch-language` | Language switching | ✅ Yes | None |
|
||||
| GET | `/toggle/length` | CV length toggle | ✅ Yes | None |
|
||||
| GET | `/toggle/icons` | Icon visibility toggle | ✅ Yes | None |
|
||||
| GET | `/toggle/theme` | Theme toggle | ✅ Yes | None |
|
||||
| GET | `/export/pdf` | PDF export | ❌ No | ✅ Rate Limited + Origin Check |
|
||||
| GET | `/cv-jamr-{year}-{lang}.pdf` | Shortcut PDF download routes | ❌ No | Redirect to /export/pdf |
|
||||
| GET | `/health` | Health check | ❌ No | None |
|
||||
| GET | `/static/*` | Static files (CSS, JS, images) | ❌ No | Cache Control |
|
||||
|
||||
@@ -379,7 +387,193 @@ Content-Type: text/html
|
||||
|
||||
**Description:** Returns a plain text version of the CV, optimized for CLI tools (curl, wget) and text browsers (lynx, w3m). Auto-detected via User-Agent header.
|
||||
|
||||
#### Query Parameters
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `lang` | string | No | `en` | Language code (`en` or `es`) |
|
||||
|
||||
#### Response
|
||||
|
||||
**Status Code:** `200 OK`
|
||||
|
||||
**Content-Type:** `text/plain; charset=utf-8`
|
||||
|
||||
**Response Body:** 80-character wrapped plain text CV with ASCII formatting
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Get plain text CV (auto-detected via curl User-Agent)
|
||||
curl http://localhost:1999/text
|
||||
|
||||
# Spanish version
|
||||
curl http://localhost:1999/text?lang=es
|
||||
|
||||
# View in text browser
|
||||
lynx http://localhost:1999/text
|
||||
```
|
||||
|
||||
#### Notes
|
||||
|
||||
- Returns CV content formatted for terminal display
|
||||
- 80-character line width for optimal terminal viewing
|
||||
- Unicode characters properly handled
|
||||
- Useful for AI assistants reading CV content
|
||||
|
||||
---
|
||||
|
||||
### 4. GET /api/cmd-k
|
||||
|
||||
**Description:** Returns JSON data for the CMD+K command palette (ninja-keys integration). Provides dynamic entries for experiences, projects, and courses that can be searched.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `lang` | string | No | `en` | Language code (`en` or `es`) |
|
||||
|
||||
#### Response
|
||||
|
||||
**Status Code:** `200 OK`
|
||||
|
||||
**Content-Type:** `application/json`
|
||||
|
||||
**Cache-Control:** `public, max-age=3600` (1 hour)
|
||||
|
||||
**Response Body:**
|
||||
```json
|
||||
{
|
||||
"experiences": [
|
||||
{"id": "exp-1", "title": "Senior Developer", "section": "experience", "keywords": "..."}
|
||||
],
|
||||
"projects": [
|
||||
{"id": "proj-1", "title": "Project Name", "section": "projects", "keywords": "..."}
|
||||
],
|
||||
"courses": [
|
||||
{"id": "course-1", "title": "Course Name", "section": "courses", "keywords": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Get CMD+K data
|
||||
curl -s http://localhost:1999/api/cmd-k | jq
|
||||
|
||||
# Count experiences
|
||||
curl -s http://localhost:1999/api/cmd-k | jq '.experiences | length'
|
||||
```
|
||||
|
||||
#### Notes
|
||||
|
||||
- Used by ninja-keys web component for command palette
|
||||
- Cached for 1 hour to reduce server load
|
||||
- Entries include scroll-to-section functionality
|
||||
|
||||
---
|
||||
|
||||
### 5. POST /api/contact
|
||||
|
||||
**Description:** Contact form submission endpoint with comprehensive security middleware chain.
|
||||
|
||||
#### Request Headers
|
||||
|
||||
| Header | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| `HX-Request` | Yes | Must be `true` (browser validation) |
|
||||
| `Referer` or `Origin` | Yes | Must match allowed origins |
|
||||
| `Content-Type` | Yes | `application/x-www-form-urlencoded` |
|
||||
|
||||
#### Request Body
|
||||
|
||||
| Field | Type | Required | Validation |
|
||||
|-------|------|----------|------------|
|
||||
| `name` | string | Yes | 2-100 characters |
|
||||
| `email` | string | Yes | Valid email format |
|
||||
| `message` | string | Yes | 10-5000 characters |
|
||||
| `_csrf` | string | Yes | Valid CSRF token from session |
|
||||
|
||||
#### Security Middleware
|
||||
|
||||
1. **BrowserOnly** - Blocks curl/Postman/bots (requires HX-Request header)
|
||||
2. **Rate Limiting** - 5 submissions per hour per IP
|
||||
3. **CSRF Protection** - Token validation against session
|
||||
|
||||
#### Response
|
||||
|
||||
**Status Code:** `200 OK` (success) or `400/403/429` (error)
|
||||
|
||||
**Content-Type:** `text/html` (HTMX partial)
|
||||
|
||||
#### Error Responses
|
||||
|
||||
| Code | Reason |
|
||||
|------|--------|
|
||||
| 400 | Validation failed (missing fields, invalid email) |
|
||||
| 403 | Security check failed (no browser headers, invalid CSRF) |
|
||||
| 429 | Rate limit exceeded (5/hour per IP) |
|
||||
| 500 | Email sending failed |
|
||||
|
||||
#### Notes
|
||||
|
||||
- See `docs/CONTACT-FORM-QUICKSTART.md` for implementation details
|
||||
- SMTP configuration via environment variables
|
||||
- Returns HTMX partial for seamless form updates
|
||||
|
||||
---
|
||||
|
||||
### 6. GET /switch-language
|
||||
|
||||
**Description:** HTMX endpoint for language switching. Returns updated UI elements.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `lang` | string | Yes | - | Target language (`en` or `es`) |
|
||||
|
||||
#### Response
|
||||
|
||||
Returns HTMX partial with updated language-specific content.
|
||||
|
||||
---
|
||||
|
||||
### 7. GET /toggle/{preference}
|
||||
|
||||
**Description:** HTMX endpoints for CV preference toggles.
|
||||
|
||||
#### Endpoints
|
||||
|
||||
- `GET /toggle/length` - Toggle CV length (short/long)
|
||||
- `GET /toggle/icons` - Toggle icon visibility (show/hide)
|
||||
- `GET /toggle/theme` - Toggle theme (default/clean)
|
||||
|
||||
#### Response
|
||||
|
||||
Returns HTMX partial with updated toggle state.
|
||||
|
||||
---
|
||||
|
||||
### 8. GET /cv-jamr-{year}-{lang}.pdf
|
||||
|
||||
**Description:** Shortcut routes for default CV PDF downloads. Redirects to `/export/pdf` with appropriate parameters.
|
||||
|
||||
#### Examples
|
||||
|
||||
```
|
||||
/cv-jamr-2025-en.pdf → /export/pdf?lang=en&length=short&icons=show&version=clean
|
||||
/cv-jamr-2025-es.pdf → /export/pdf?lang=es&length=short&icons=show&version=clean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. GET /export/pdf
|
||||
|
||||
**Description:** Generates and downloads a PDF version of the CV using headless Chrome (chromedp). The PDF is generated from the rendered HTML page with customizable parameters for language, length, icons, and version.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
@@ -2051,6 +2245,6 @@ go tool trace trace.out
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** November 12, 2025
|
||||
**API Version:** 1.1.0
|
||||
**Documentation Version:** 1.1.0
|
||||
**Last Updated:** December 1, 2025
|
||||
**API Version:** 1.2.0
|
||||
**Documentation Version:** 1.2.0
|
||||
|
||||
Reference in New Issue
Block a user