gooneral_wheelchair/WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

"The gooneral wheelchair" is a full-stack personal CMS (Content Management System) built with React frontend and Node.js/Express backend. The system provides both a public blog interface and a complete admin dashboard for managing posts dynamically through a REST API.

Development Commands

Full-Stack Development

• Start both servers: npm run dev - Runs both frontend (Vite) and backend (Express) servers concurrently
• Frontend only: npm run dev:frontend - Runs Vite dev server on port 5173
• Backend only: npm run dev:backend - Runs Express API server on port 3001

Production Commands

• Build frontend: npm run build - Creates optimized production build in dist/
• Start backend: npm run start:backend - Starts production Express server
• Preview frontend: npm run preview - Serves the built application locally

Code Quality

• Lint code: npm run lint - Runs ESLint on all JavaScript/JSX files

Package Management

• Install all dependencies: npm install && cd backend && npm install
• Add frontend dependency: npm install <package-name>
• Add backend dependency: cd backend && npm install <package-name>
• Add dev dependency: npm install -D <package-name>

Architecture Overview

Full-Stack Architecture

• Frontend: React SPA with React Router for navigation
• Backend: Node.js/Express API server with REST endpoints
• Database: File-system based (markdown files in public/posts/)
• Communication: Frontend communicates with backend via REST API calls

Frontend Structure

• Entry Point: src/main.jsx - React application entry with StrictMode
• Main Router: src/App.jsx - React Router setup with route definitions
• Components:
  • BlogHome - Public blog homepage with post grid
  • PostView - Individual post display component
  • AdminDashboard - Admin interface for managing posts
  • PostEditor - Create/edit post interface with live preview
• Styling: Tailwind CSS 4.x via Vite plugin

Backend API Structure

• Server: backend/server.js - Express server with CORS and session management
• Authentication: Session-based authentication with bcrypt password hashing
• API Base URL: http://localhost:3001/api
• Public Endpoints:
  • GET /api/posts - Fetch all posts with metadata
  • GET /api/posts/:slug - Fetch specific post
  • GET /api/health - Health check endpoint
• Authentication Endpoints:
  • POST /api/auth/login - User login
  • POST /api/auth/logout - User logout
  • GET /api/auth/me - Get current user info
  • POST /api/auth/change-password - Change user password (requires auth)
• Protected Endpoints (require admin authentication):
  • POST /api/posts - Create new post
  • PUT /api/posts/:slug - Update existing post
  • DELETE /api/posts/:slug - Delete post

Content Management System

The CMS operates on a hybrid approach:

1. Post Storage: Markdown files in public/posts/ directory
2. API Layer: Express server handles CRUD operations on markdown files
3. Dynamic Index: Backend automatically generates index.json when posts change
4. Metadata Handling: Server-side parsing of frontmatter (title:, desc:, tags:)
5. Admin Interface: Full CRUD interface accessible at /admin

Markdown Processing Pipeline

The application uses an extensive MarkdownIt setup with multiple plugins:

• Base Configuration: HTML enabled, linkify, typographer
• Extensions: Emoji, abbreviations, subscript/superscript, insertions, marks, definition lists, footnotes, spoilers
• Custom Containers: Info, warning, and spoiler containers
• Table Enhancement: Wraps tables in scrollable containers
• Sanitization: DOMPurify for XSS protection

Client-Side Routing

• Uses React Router for navigation
• Route pattern: /posts/{slug} maps to post slugs
• Home route / shows post grid
• Admin routes under /admin for content management

Routing Structure

Frontend Routes:

• / - Blog homepage (BlogHome component)
• /posts/:slug - Individual post view (PostView component)
• /login - Login form (LoginForm component)
• /admin - Admin dashboard (AdminDashboard component) - Protected
• /admin/post/new - Create new post (PostEditor component) - Protected
• /admin/post/:slug/edit - Edit existing post (PostEditor component) - Protected

API Routes:

• GET /api/posts - List all posts
• GET /api/posts/:slug - Get single post
• POST /api/posts - Create post
• PUT /api/posts/:slug - Update post
• DELETE /api/posts/:slug - Delete post

File Structure Patterns

Frontend Source Code

• src/App.jsx - Main router component with route definitions and auth integration
• src/main.jsx - React entry point
• src/index.css - Global styles (Tailwind imports)
• src/contexts/AuthContext.jsx - Authentication context and state management
• src/components/AdminDashboard.jsx - Admin interface component
• src/components/PostEditor.jsx - Post creation/editing interface
• src/components/LoginForm.jsx - User login form
• src/components/ProtectedRoute.jsx - Route protection wrapper

Backend Source Code

• backend/server.js - Express API server with authentication
• backend/auth.js - Authentication utilities and user management
• backend/users.json - User data storage (auto-generated)
• backend/package.json - Backend dependencies and scripts

Content

• public/posts/*.md - Blog post markdown files (managed via API)
• public/posts/index.json - Auto-generated file list (managed by backend)
• public/posts/image.png - Post assets (images referenced in markdown)

Configuration

• package.json - Frontend dependencies and development scripts
• backend/package.json - Backend dependencies
• vite.config.js - Vite configuration with React and Tailwind (no custom plugins)
• eslint.config.js - ESLint configuration with React rules

Development Workflow

Adding New Posts

Via Admin Interface (Recommended):

1. Navigate to /admin in your browser
2. Click "New Post" button
3. Fill in title, description, tags, and content
4. Use the Preview tab to see rendered markdown
5. Click "Create Post" to save

Manual File Creation:

1. Create new .md file in public/posts/ directory
2. Include frontmatter: title: Your Title, desc: Description, tags: tag1, tag2
3. Write content using supported markdown extensions
4. Restart backend server to recognize new file

Editing Posts

Via Admin Interface:

1. Go to /admin and click "Edit" on any post
2. Modify content in the editor with live preview
3. Click "Update Post" to save changes

Direct File Editing:

1. Edit the .md file directly in public/posts/
2. Changes will be reflected immediately via API

Markdown Features Supported

WYSIWYG Editor Features:

• Visual toolbar: Quick access to formatting (bold, italic, headers, lists, links, images, code)
• Multiple editing modes: Edit, Preview, and Live (split) modes
• Syntax highlighting: Enhanced code editing with monospace font
• Drag-to-resize: Adjustable panes in live mode

Standard Markdown Syntax Support:

• Text formatting: Bold, italic, strikethrough
• Headers: All levels (H1-H6)
• Lists: Ordered and unordered (with nesting)
• Links and images: Standard [text](url) and ![alt](src) syntax
• Code: Inline code and fenced code blocks with syntax highlighting
• Tables: GitHub-style tables (automatically made scrollable)
• Blockquotes: Standard > syntax, great for callouts with emoji
• Horizontal rules: --- or ***
• HTML support: Standard HTML tags when needed
• Emoji: GitHub-style :emoji_name: syntax
• Footnotes: Standard [^ref] syntax
• Collapsible content: HTML <details><summary> tags
• Line breaks: Proper paragraph handling

Code Style

• Uses ESLint with React-specific rules
• Unused variables allowed if they follow ^[A-Z_] pattern
• ES2020+ features enabled
• JSX support configured

Markdown Compatibility

• Standards-compliant: Uses only widely-supported markdown features
• Portable content: Markdown files work with GitHub, GitLab, and other platforms
• No custom extensions: Avoids proprietary syntax that doesn't work elsewhere
• HTML fallback: When markdown isn't enough, standard HTML tags are supported

Custom Implementation Notes

State Management

Each React component manages its own state with useState hooks:

• BlogHome: posts, loading, error - For blog homepage
• PostView: post, loading, error - For individual post display
• AdminDashboard: posts, loading, error - For admin post list
• PostEditor: formData, loading, saving, error, previewMode - For post editing

API Integration

All components use fetch() to communicate with the Express backend:

• Base URL: http://localhost:3001/api
• Error Handling: Consistent error states across components
• Loading States: All API calls show loading indicators
• CRUD Operations: Full create, read, update, delete functionality

Unusual Function Names

The codebase contains intentionally obscure function names (e.g., giveFoxHerHeir, getTingyun, travelToExpress, conceiveFoxFromSemen) - this appears to be a stylistic choice and should be preserved when making changes.

Content Processing

• Metadata extracted via regex patterns from markdown content
• HTML content sanitized with DOMPurify before rendering
• Dynamic title updates based on selected post
• Custom image credit parsing for blog post assets

Development Setup

Initial Setup

1. Install frontend dependencies: npm install
2. Install backend dependencies: cd backend && npm install
3. Start development servers: npm run dev
4. Frontend will be available at http://localhost:5173
5. Backend API will be available at http://localhost:3001
6. Admin interface accessible at http://localhost:5173/admin

Production Deployment

Frontend: Can be deployed to static hosting (Netlify, Vercel, etc.) Backend: Requires Node.js server environment (Heroku, Railway, DigitalOcean, etc.) Database: File system based, no external database required

Environment Variables

• PORT - Backend server port (default: 3001)
• NODE_ENV - Environment mode for backend

Authentication System

Default Credentials

• Username: admin
• Password: admin123
• ⚠️ IMPORTANT: Change the default password immediately after first login

Security Features

• Session-based authentication with secure cookies
• Bcrypt password hashing (10 rounds)
• Protected API endpoints require admin role
• Frontend route protection with automatic redirects
• Session timeout after 24 hours of inactivity

User Management

• Single admin user system (expandable)
• Password change functionality in admin interface
• Automatic user file creation on first server start
• Session persistence across browser sessions

Admin Interface Features

Authentication Flow

1. Navigate to /admin without authentication → redirected to /login
2. Login with credentials → redirected to intended admin page
3. Admin navigation only visible when authenticated
4. Logout clears session and redirects to homepage

Dashboard (/admin) - Requires Authentication

• Overview statistics (total posts, recent posts)
• Post management table with edit/delete actions
• Quick access to create new posts
• User greeting and logout functionality

Post Editor (/admin/post/new or /admin/post/:slug/edit) - Requires Authentication

• Rich form interface for post metadata (title, description, tags)
• WYSIWYG Markdown Editor with multiple editing modes:
  • Edit Mode: Source code editing with syntax highlighting
  • Preview Mode: Live rendered markdown preview
  • Live Mode: Split view with edit and preview side-by-side
• Visual toolbar with formatting buttons (bold, italic, headers, lists, links, etc.)
• Drag-to-resize editor panes in live mode
• Full support for standard markdown features (tables, footnotes, emoji, HTML tags)
• Save/cancel actions with error handling
• Automatic slug generation from title for new posts

Login Form (/login)

• Clean, responsive login interface
• Error handling for invalid credentials
• Default credentials display for initial setup
• Automatic redirect after successful login