documentation

Author: zerox80

src/api/client.js

@@ -1,3 +1,17 @@
+/**
+ * API Client Module
+ * 
+ * A centralized wrapper for making HTTP requests to the backend API.
+ * 
+ * Key Features:
+ * - **Base URL Resolution**: Automatically determines the API base URL based on environment (Vite env vars or window location).
+ * - **Authentication**: Manages JWT tokens, automatically attaching them to requests and handling 401 Unauthorized responses.
+ * - **CSRF Protection**: Automatically extracts and includes the `x-csrf-token` header for mutating requests.
+ * - **AbortController Integration**: Supports request cancellation via `AbortController` signals.
+ * - **Timeout Handling**: Implements request timeouts (default 15s) with cleanup.
+ * - **Response Parsing**: Automatically parses JSON responses and handles edge cases like empty bodies or non-JSON errors.
+ * - **File Uploads**: Provides a helper for `multipart/form-data` uploads.
+ */
 export const getApiBaseUrl = () => {
   if (import.meta.env.VITE_API_BASE_URL) {
     return import.meta.env.VITE_API_BASE_URL.replace(/\/+$/, '')

src/components/Hero.jsx

@@ -5,13 +5,45 @@ import { useContent } from '../context/ContentContext'
 import { getIconComponent } from '../utils/iconMap'
 import { scrollToSection } from '../utils/scrollToSection'
 import { sanitizeExternalUrl } from '../utils/urlValidation'
+
+/**
+ * A generic Hero section component used for standard pages.
+ * 
+ * Unlike the specialized `LandingHero`, this component is designed for reusability
+ * across different pages. It supports a configurable title, subtitle, CTA buttons,
+ * and a grid of feature highlights.
+ * 
+ * Key Features:
+ * - Dynamic Icon Resolution: Loads icons based on CMS string identifiers.
+ * - Smart Navigation: Handles internal routes, external links, and anchor scrolling via `handleTarget`.
+ * - Visuals: Features a background gradient with decorative blur blobs and a pattern overlay.
+ * 
+ * @component
+ * @example
+ * // Usage within a page component
+ * <Hero />
+ */
 const Hero = () => {
   const navigate = useNavigate()
   const location = useLocation()
   const { getSection } = useContent()
   const heroContent = getSection('hero') ?? {}
   const HeroIcon = useMemo(() => getIconComponent(heroContent.icon, 'Terminal'), [heroContent.icon])
   const features = Array.isArray(heroContent.features) ? heroContent.features : []
+
+  /**
+   * Unified handler for processing navigation actions.
+   * 
+   * Abstracts away the complexity of different link types:
+   * - `section`: Scrolls to an ID on the home page (handling cross-page jumps if needed).
+   * - `route`: Standard SPA client-side navigation.
+   * - `external`: Opens in new tab with security attributes (noopener, noreferrer).
+   * - `href`: Direct window location assignment (for special protocols or hard refreshes).
+   * 
+   * @param {Object} target - The target definition object from CMS.
+   * @param {string} target.type - The type of navigation ('section', 'route', 'external', 'href').
+   * @param {string} target.value - The destination path, URL, or ID.
+   */
   const handleTarget = (target) => {
     if (!target || !target.type) {
       return

src/components/layout/Footer.jsx

@@ -55,6 +55,17 @@ const resolveContactFallbackIcon = (contact) => {
 
 import EditableText from '../cms/EditableText'
 
+/**
+ * The global site footer component.
+ * 
+ * Aggregates navigation links, contact info, and branding into a structured layout.
+ * 
+ * Architecture:
+ * - **Data Source**: Pulls `footer` section data and `navigation` structure from `ContentContext`.
+ * - **Dynamic Links**: Merges specifically configured `quickLinks` with the global navigation tree.
+ * - **CMS Integration**: All text elements (Brand, Copyright, Links) are wrapped in `EditableText`.
+ * - **Safety**: Sanitizes all external URLs to prevent XSS/Phishing via `sanitizeExternalUrl`.
+ */
 const Footer = () => {
     const { getSection, navigation } = useContent()
     const footerContent = getSection('footer') ?? {}

src/context/AuthContext.jsx

@@ -4,6 +4,16 @@ import { api } from "../api/client"
 
 const AuthContext = createContext(null)
 
+/**
+ * Global Authentication Provider.
+ * 
+ * Manages the user's session state, including login, logout, and token validation.
+ * 
+ * Architecture:
+ * - **Initialization**: Checks `/api/me` on mount to re-hydrate session from HTTP-only cookie.
+ * - **Security**: Uses `AbortController` to prevent memory leaks during async auth checks.
+ * - **Error Handling**: fails gracefully to "Unauthenticated" state on API errors (401/500).
+ */
 export const AuthProvider = ({ children }) => {
   const [isAuthenticated, setIsAuthenticated] = useState(false)
   const [user, setUser] = useState(null)
@@ -12,7 +22,7 @@ export const AuthProvider = ({ children }) => {
 
   useEffect(() => {
     const controller = new AbortController()
-    
+
     const checkAuth = async () => {
       try {
         const userData = await api.me();
@@ -28,17 +38,17 @@ export const AuthProvider = ({ children }) => {
         // but for the purpose of UI state, we treat them as not authenticated.
         // However, if it's a 401, the api client might have already cleared it or we should ensure it's cleared.
         if (err?.status === 401) {
-            api.setToken(null);
+          api.setToken(null);
         }
       } finally {
         if (!controller.signal.aborted) {
           setLoading(false)
         }
       }
     }
-    
+
     checkAuth()
-    
+
     return () => {
       controller.abort()
     }
@@ -48,27 +58,27 @@ export const AuthProvider = ({ children }) => {
     try {
       setError(null)
       setLoading(true)
-      
+
       const sanitizedUsername = username.trim()
       const response = await api.login(sanitizedUsername, password)
-      
+
       if (!response?.user) {
         throw new Error('Ungueltige Antwort vom Server')
       }
-      
+
       api.setToken(response.token ?? null)
       setIsAuthenticated(true)
       setUser(response.user)
-      
+
       return { success: true }
     } catch (err) {
       api.setToken(null)
       setIsAuthenticated(false)
       setUser(null)
-      
+
       const message = err.message || 'Ungueltige Anmeldedaten'
       setError(message)
-      
+
       return { success: false, error: message }
     } finally {
       setLoading(false)
@@ -101,10 +111,10 @@ AuthProvider.propTypes = {
 
 export const useAuth = () => {
   const context = useContext(AuthContext)
-  
+
   if (!context) {
     throw new Error('useAuth must be used within AuthProvider')
   }
-  
+
   return context
 }

src/context/TutorialContext.jsx

@@ -4,6 +4,16 @@ import { api } from '../api/client'
 import { getIconComponent as getIconComponentFromMap } from '../utils/iconMap'
 const TutorialContext = createContext(null)
 
+/**
+ * Global Tutorial Data Provider.
+ * 
+ * Centralizes the fetching, caching, and management of tutorial content.
+ * 
+ * Features:
+ * - **Resilient Fetching**: Implements exponential backoff retry logic (up to 3 attempts) for flaky networks.
+ * - **CRUD Operations**: Exposes `add`, `update`, and `delete` methods that sync local state with backend.
+ * - **Abort Safety**: Cancels in-flight requests on unmount to prevent state updates on destroyed components.
+ */
 export const TutorialProvider = ({ children }) => {
   const [tutorials, setTutorials] = useState([])
   const [loading, setLoading] = useState(true)

src/pages/Home.jsx

@@ -3,6 +3,16 @@ import { useLocation, useNavigate } from 'react-router-dom'
 import Hero from '../components/Hero'
 import TutorialSection from '../components/TutorialSection'
 import { scrollToSection } from '../utils/scrollToSection'
+
+/**
+ * The application's homepage component.
+ * 
+ * Acts as the primary landing point for authenticated or returning users.
+ * 
+ * Features:
+ * - Smart Scroll Restoration: Handles `location.state.scrollTo` to jump to specific sections upon navigation.
+ * - Composition: Combines the `Hero` (standard) and `TutorialSection` components.
+ */
 const Home = () => {
   const location = useLocation()
   const navigate = useNavigate()

src/pages/PostDetail.jsx

@@ -14,14 +14,7 @@ import { Calendar, Clock, User, ArrowLeft, Share2, Bookmark } from 'lucide-react
  * - Table of Contents (ToC): Implements a Scroll-Spy to highlight current section.
  * - Dynamic SEO: Injects post-specific meta tags for social sharing and search.
  * - Advanced Meta: Calculates "Read Time" if not provided by backend.
- */
-/**
- * Detailed Tutorial Viewer.
- * 
- * Features:
- * - Hybrid Loading: Attempts to use cached context data before fetching from API.
- * - Modular Rendering: Decouples header, topics, and content for scalability.
- * - Nav Logic: Intelligent "Go Back" that stays within app history when possible.
+ * - Interaction: Integrated comments section and share functionality.
  */
 const PostDetail = () => {
   const { pageSlug, postSlug } = useParams()
@@ -73,6 +66,8 @@ const PostDetail = () => {
 
   if (!post) return <div className="min-h-screen flex items-center justify-center text-slate-400">Loading...</div>
 
+  const readTimeDisplay = post.readTime || `${ Math.ceil((post.content_markdown?.length || 0) / 1000) + 1 } min read`
+
   return (
     <div className="min-h-screen bg-slate-950 pt-24 pb-20">
       <Helmet>
@@ -115,7 +110,7 @@ const PostDetail = () => {
             </div>
             <div className="flex items-center gap-2">
               <Clock className="w-4 h-4" />
-              <span>{post.readTime || `${ Math.ceil((post.content_markdown?.length || 0) / 1000) + 1 } min read`}</span>
+              <span>{readTimeDisplay}</span>
             </div>
           </div>
         </div>

src/utils/pwa.js

@@ -1,5 +1,15 @@
 // Global variable to store the install prompt event
 let deferredPrompt = null;
+
+/**
+ * Service Worker Registration and PWA Install Logic.
+ * 
+ * Functions:
+ * - `registerServiceWorker`: Registers the SW script (`/sw.js`) for offline capabilities.
+ * - `initPWA`: Listens for the `beforeinstallprompt` event to enable custom install UI.
+ * - `installPWA`: Triggers the browser's native install prompt when the user clicks the install button.
+ * - `isPWAInstalled`: Checks if the app is running in standalone mode (installed).
+ */
 export const registerServiceWorker = async () => {
   if ('serviceWorker' in navigator) {
     try {

src/utils/remarkMergeInlineParagraphs.js

@@ -1,5 +1,10 @@
 
-
+/**
+ * Remark Plugin: Merge Inline Paragraphs (Stub).
+ * 
+ * Placeholder plugin structure for future implementation of AST transformations.
+ * Currently performs no-op traversals.
+ */
 const tightenListItems = () => { }
 const reattachDanglingParagraphs = () => { }
 const mergeLooseParagraphs = () => { }

src/utils/sanitize.js

@@ -1,4 +1,11 @@
 import DOMPurify from 'dompurify';
+
+/**
+ * HTML Sanitization Utilities.
+ * 
+ * Wraps DOMPurify to provide strict, configured sanitization for HTML content.
+ * Prevents XSS attacks by stripping dangerous tags and attributes.
+ */
 const DEFAULT_CONFIG = {
   ALLOWED_TAGS: [
     'p', 'br', 'strong', 'em', 'u', 's', 'a', 'ul', 'ol', 'li',