# 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