# Admin Panel Guide

Complete guide to using the Admin Panel for managing your portfolio website content, themes, and settings.

## 🔐 Accessing the Admin Panel

### Login

1. Navigate to **[http://localhost:3000/admin](http://localhost:3000/admin)** (or your domain/admin)
2. Enter your credentials:
   - **Username**: Your `ADMIN_USERNAME` from `.env`
   - **Password**: Your `ADMIN_PASSWORD` from `.env`
3. Click "Sign In"

### Authentication

- Sessions last for **24 hours**
- JWT token is stored securely in httpOnly cookie
- Auto-logout on token expiration
- Password is hashed using bcrypt

## 📊 Dashboard Overview

After login, you'll see the admin dashboard with:

- **Quick Stats**: Total projects, blogs, gallery items, messages
- **Recent Activity**: Latest content additions and updates
- **System Status**: Database connection, storage usage
- **Quick Actions**: Create project, write blog, upload images
- **Brain Core**: AI Neural Core status and master switch


## 📝 Content Management

### Managing Projects

**Path**: Admin Panel → Projects

#### Creating a New Project

1. Click **"Add New Project"**
2. Fill in project details:
   - **Title**: Project name (3-100 characters)
   - **Slug**: URL-friendly identifier (auto-generated)
   - **Description**: Brief overview (10-500 characters)
   - **Content**: Full project description (Markdown supported)
   - **Featured Image**: Main project image
   - **Gallery Images**: Additional screenshots (drag to reorder)
   - **Tech Stack**: Technologies used (comma-separated)
   - **Tags**: Category tags
   - **Links**:
     - Live Demo URL
     - GitHub Repository URL
     - Documentation URL (optional)
   - **Status**: Draft or Published
   - **Featured**: Show on homepage

3. Click **"Save Project"**

#### Editing Projects

1. Click on project in list
2. Modify any field
3. Click **"Update Project"**
4. Changes are live immediately

#### Markdown Editor Features

- **Live Preview**: See formatted content in real-time
- **Syntax Highlighting**: Code blocks with language support
- **Image Embedding**: Drag and drop images
- **Tables**: Create data tables
- **Lists**: Ordered and unordered lists
- **Headers**: H1 to H6
- **Links**: Internal and external links
- **Bold/Italic**: Text formatting

#### Project Gallery Management

1. **Upload Images**: Drag and drop or click to browse
2. **Reorder**: Drag images to change order
3. **Delete**: Click X to remove image
4. **Add Caption**: Click image to add description
5. **Set Featured**: Mark one as featured image

#### GitHub Integration

1. Add **GitHub Token** in Settings
2. Enter **Repository URL** in project form
3. Click **"Fetch Stats"**
4. Displays:
   - Stars count
   - Forks count
   - Primary language
   - Last updated date
   - Open issues

### Managing Blogs

**Path**: Admin Panel → Blogs

#### Creating a Blog Post

1. Click **"Write New Post"**
2. Fill in details:
   - **Title**: Post title (10-200 characters)
   - **Slug**: URL identifier (auto-generated)
   - **Excerpt**: Brief summary
   - **Content**: Full article (Markdown with GFM)
   - **Featured Image**: Header image
   - **Tags**: Topic tags
   - **Category**: Main category
   - **Status**: Draft or Published
   - **Publish Date**: Schedule publication

3. Click **"Publish"** or **"Save Draft"**

#### Blog Editor Features

- **Markdown Support**: GitHub Flavored Markdown (GFM)
- **Code Blocks**: Syntax highlighting with 100+ languages
- **Live Preview**: Real-time rendering
- **Auto-save**: Saves draft every 30 seconds
- **Image Upload**: Inline image insertion
- **Table of Contents**: Auto-generated from headers
- **Reading Time**: Automatically calculated

#### Draft Workflow

1. Write post in **Draft** mode
2. Preview before publishing
3. Change status to **Published** when ready
4. Unpublish anytime by setting to Draft

#### Blog API Integration

Automate blog posting from external systems:

```bash
curl -X POST http://localhost:3000/api/blog/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_BLOG_API_KEY" \
  -d '{
    "title": "My New Blog Post",
    "content": "# Hello World\n\nThis is my post.",
    "excerpt": "A great post",
    "tags": ["tech", "programming"],
    "status": "published"
  }'
```

**Use cases**:
- Notion → Portfolio blog automation
- RSS feed integration
- Cross-posting from Medium/Dev.to
- Automated publishing workflows

### Managing Apps

**Path**: Admin Panel → Apps

A directory of your hosted apps/services, shown alongside your projects on the public site.

1. Click **"Add App"**
2. Fill in:
   - **App Name** and **App Type**
   - **Description**
   - **Hosting Provider** and **Environment**
   - **Tech Stack**
   - **Hosted URL**
   - **Status**: Live, Maintenance, Private, or Archived
   - **Image**: upload a preview/icon
   - **AI Assist**: toggle AI-generated content for the description
3. **Drag to reorder** the list; delete an entry with its trash icon

### AI Hub Page

**Path**: Admin Panel → AI Hub (`/admin/ai-page`)

Manages the public **`/ai`** showcase page.

#### Content Tab
- **Skills**: name, URL, rating (0–5), accent color, blurb, tags
- **Recommendations**: name, offer, URL, "free API key" / "no credit card" switches, note
- **Prompt Library**: title, role/tag, prompt text
- **Free Credits**: promotional entries for free-tier offers

#### Layout Tab
- Reorder and toggle sections and headings
- Edit the hero and stats blocks
- **Seed Defaults**: one-time backfill that only fills in empty sections (safe to run repeatedly)

### Resume Studio

**Path**: Admin Panel → Resume Studio (`/admin/resume`)

A full-screen LaTeX resume IDE with a live PDF preview.

#### Editor Modes
- **Code Mode**: CodeMirror LaTeX editor with syntax highlighting
- **Visual Mode**: the parsed resume renders as drag-and-drop section cards with plain form fields instead of raw LaTeX

#### Toolbar
- **Save**, **Compile** (renders the PDF inline; failures show a clickable error log with line-jump)
- **Publish**: save → compile → upload pipeline, publishes to your live resume in one click (shows a one-time explainer dialog, dismissible)
- **PDF**: download the compiled file
- **Save Version**: snapshot the current document

#### Settings Popover
- **LaTeX Engine** select (e.g. `pdflatex`)
- **Auto-Save** and **Auto-Compile** toggles (debounced; enabling auto-compile also enables auto-save)

#### Side Panel Tabs
- **Items**: insert Projects / Hosted Apps / Experience / Education / Skills from your live site data as ready-made LaTeX blocks
- **Design**: color theme presets (swap just the theme block) and starter Templates (replace the whole document — destructive)
- **AI**: refine the current selection, auto-fix compile errors, tailor the resume to a pasted job description, or freeform "generate LaTeX"
- **Ideas**: a notes/ideas board for resume content
- **Versions**: named snapshots you can save, switch between, rename, update, or delete (capped at a maximum count)

#### Visual Mode Header & Sections
- Dedicated GUI form for the header block (contact rows with type/icon/label)
- **Add Section** menu with presets: Experience, Education, Projects, Skills, Summary, Certifications, Achievements, Involvement, or Raw LaTeX

### Managing Gallery

**Path**: Admin Panel → Gallery

#### Uploading Images

1. Click **"Upload Images"**
2. Select or drag multiple images
3. Supported formats:
   - JPEG/JPG
   - PNG
   - WebP
   - HEIC/HEIF

4. Images are automatically:
   - Optimized (WebP conversion)
   - Resized (max 1920x1080)
   - Compressed (quality 80)

#### Gallery Item Details

For each image, add:
- **Title**: Achievement or award name
- **Description**: Brief details
- **Date**: When received
- **Category**: Award type
- **URL**: External link (optional)

#### Gallery Layout

- **Masonry Grid**: Responsive layout
- **Lazy Loading**: Images load on scroll
- **Lightbox**: Click to view full size
- **EXIF Data**: Preserves photo metadata

### Managing Contact Messages

**Path**: Admin Panel → Messages

#### Viewing Messages

Messages are displayed in a **chat-style interface**:

- **Unread**: Bold with blue indicator
- **Read**: Normal text
- **Starred**: Yellow star icon
- **Replied**: Green check mark

#### Message Actions

1. **Mark as Read/Unread**: Toggle read status
2. **Star**: Flag important messages
3. **Reply**: Send response via email
4. **Delete**: Remove message permanently
5. **Export**: Download as CSV

#### Message Details

Each message shows:
- Sender name and email
- Message content
- Timestamp
- IP address (for security)
- User agent (browser/device)

#### Bulk Actions

1. Select multiple messages with checkboxes
2. Choose action:
   - Mark all as read
   - Delete selected
   - Export selected

## 🎨 Theme Customization

**Path**: Admin Panel → Themes

### Choosing a Pre-built Theme

1. Browse **52 pre-built themes**:
   - VS Code Dark
   - Ocean Blue
   - Forest Green
   - Sunset Orange
   - Royal Purple
   - Monochrome
   - Dracula
   - Nord
   - Cyberpunk
   - Gruvbox
   - Solarized
   - Catppuccin
   - Tokyo Night
   - Material Ocean
   - Synthwave
   - And more...

2. Click **"Preview"** to see theme
3. Click **"Apply"** to activate

### Creating Custom Theme

1. Click **"Create Custom Theme"**
2. Configure colors:
   - **Primary**: Main brand color
   - **Secondary**: Accent color
   - **Background**: Page background
   - **Surface**: Card/panel background
   - **Text**: Primary text color
   - **Text Secondary**: Muted text
   - **Border**: Border color
   - **Success/Warning/Error**: Status colors

3. Configure fonts:
   - **Heading Font**: For titles
   - **Body Font**: For content
   - **Mono Font**: For code

4. Configure spacing and borders:
   - **Spacing Unit**: Base spacing (4px)
   - **Border Radius**: Corner roundness

5. **Live Preview**: Changes appear in real-time
6. **Save Theme**: Name and save configuration

### Theme Export/Import

**Export**:
1. Click **"Export Theme"**
2. Download JSON file
3. Share with others

**Import**:
1. Click **"Import Theme"**
2. Select JSON file
3. Review and apply

### Theme Reset

**Reset to Default**:
1. Click **"Reset Theme"**
2. Confirm action
3. Returns to VS Code Dark theme

### Classic vs V2 Site

**Path**: Admin Panel → Version (`/admin/version`)

Choose which design your visitors see by default.

- Pick **Classic** or **V2** in a card selector — this sets `defaultSiteVersion` and controls what loads at the clean URLs (`/`, `/about-me`, etc.)
- Whichever version isn't the default is still reachable under its explicit prefix — `/v1` or `/v2`
- Routing happens via URL rewrite (no cookie); changes take effect within ~30 seconds through the proxy cache
- **V2** is an alternate "editorial depth" redesign — numbered chapters, hairline ledger rows, GSAP scroll-depth animation, terminal-style chrome — covering landing, about, projects, gallery, contact, GitHub, apps, and sitemap pages

## ⚙️ Configuration

### Global Settings

**Path**: Admin Panel → Config → Global Settings

Configure site-wide settings:

#### Site Information
- Site name and tagline
- Author information
- Contact email
- Social media profiles

#### SEO Configuration
- Meta title template
- Meta description
- Keywords
- Open Graph image
- Twitter card settings

#### Analytics
- Google Analytics ID
- Enable/disable tracking
- Track outbound links
- Privacy mode

#### Feature Flags
- Enable/disable blog
- Enable/disable gallery
- Enable/disable contact form
- "Open to Work" status

### 🔔 Notification Settings

**Path**: Admin Panel → Config → Notification Integration (`/admin/config/notification`)

Configure unified alerts for system actions (like new contact form submissions).

#### Global Configuration
- **Master Switch**: Toggle notifications globally.
- **Trigger Triggers**: Link notification dispatches to new contact form messages (`notifyOnContactMessage`).

#### Integration Channels
1. **ntfy.sh (Push Notifications)**:
   - Configure Server URL (default: `https://ntfy.sh`)
   - Specify custom Topic for instant phone/desktop notifications
   - Optional security/bearer Token for protected servers
2. **Telegram Bot Integration**:
   - Bot Token: Secure token generated via BotFather
   - Chat ID: Target group or personal chat identifier
   - Formats alerts elegantly using Markdown
3. **Discord Webhooks**:
   - Webhook URL: Instantly route alerts to your Discord channels
   - Generates visually appealing embedded cards containing the sender name, email, and message snippet

---

### ⏰ Task Scheduler (Cron Jobs)

**Path**: Admin Panel → Config → Task Scheduler (`/admin/config/crons`)

Orchestrate system-defined background processes and user-defined API integration hooks.

#### Core Engine Features
- **Ticking Scheduler**: A continuous 60-second background ticker loops and matches active schedules.
- **Visual Cron Builder**: Simple selector interface to construct schedules (Every X Minutes, Hourly, Daily, Weekly, Monthly) without manual cron syntax input.
- **Expression Translation**: Real-time parser translates cron strings (e.g. `*/15 * * * *`) into human-readable text like "Every 15 minutes".
- **Dynamic Variable Guide**: Visual card documenting how to use dynamic references and functions (e.g., date-time, variables) inside expressions.

#### Maintenance Tasks (System Defined)
- **Unreferenced Upload Cleaner**: Scans file uploads and purges orphans not linked to projects or blogs.
- **Legacy Image WebP Converter**: Scans uploads for heavy PNG/JPG files, auto-optimizes to compressed WebP, updates all model assets, and purges source files.

#### Custom Webhook Hooks (User Defined)
- Register API hooks to fire on specific intervals.
- Specify target Method (POST, GET, PUT) and Webhook Endpoint.
- **Fixed/Expression Switch Toggles**: Choose between "Fixed" or "Expression" compilation mode for custom **HTTP Headers** and **Request Body**. Fixed modes treat values as raw, whereas Expression modes compile dynamic references (like dates or page-level collections) on the fly with live evaluation previews below the fields.
- **Global Environment Secrets**: Add global environment keys (`CronEnv`) securely encrypted with AES-256 in PostgreSQL. Evaluated using the `$env.KEY` format in webhook payloads and headers. Sensitive values are safely masked as `[SECRET: KEY]` in the front-end preview pane. Accessible via a dedicated global secrets modal located between the refresh and create task buttons.
- **Predefined System Variables**: Refer to `$site` for dynamic site URL evaluation and `$device` for context-aware host machine specs (supports both the full metadata object and sub-properties like `$device.platform` and `$device.os`).
- **Execution Logs**: Retain exact timestamp, success status, and detailed return strings for every scheduled run.

---

### 📺 Google AdSense Script Injection

**Path**: Admin Panel → Ads (`/admin/ads`)

Incorporate AdSense monetization into your portfolio safely.
- **Script Injector**: Enter your AdSense script tag to dynamically insert it across all public page headers.
- **Script Validation Status**: Header preview panel displays script code safely and logs live injection status.

---

### Header Configuration

**Path**: Admin Panel → Config → Header

Customize navigation:

1. **Logo**:
   - Text logo or image
   - Logo size and position

2. **Navigation Menu**:
   - Add/remove menu items
   - Reorder items (drag and drop)
   - Set labels and URLs
   - Toggle active state

3. **Theme Toggle**:
   - Show/hide theme switcher
   - Position (left/right)

### Footer Configuration

**Path**: Admin Panel → Config → Footer

Customize footer:

1. **Copyright Text**: Customize copyright notice
2. **Version**: Display version number
3. **Social Links**:
   - Add social media icons
   - Supported platforms: GitHub, LinkedIn, Twitter, Instagram, Facebook, YouTube

4. **Footer Links**:
   - Privacy policy
   - Terms of service
   - Custom links

## 🔗 GitHub Integration

**Path**: Admin Panel → GitHub Integration

### Setup

1. Generate **GitHub Personal Access Token**:
   - Go to GitHub Settings → Developer settings → Personal access tokens
   - Create new token (classic)
   - Select scopes: `public_repo`, `read:user`
   - Copy token

2. Add token in admin panel:
   - Paste token in **GitHub Token** field
   - Enter your **GitHub Username**
   - Click **"Save Settings"**

### Features

- **Repository Statistics**: Stars, forks, language
- **Activity Feed**: Recent commits and contributions
- **Auto-sync**: Update stats daily
- **Project Integration**: Link projects to repositories

### Repository Sync

1. Enter repository URL in project form
2. Click **"Fetch Stats"**
3. Stats are displayed on project page
4. Auto-updates every 24 hours

## 🔌 MCP Server

**Path**: Admin Panel → MCP Server (`/admin/mcp`)

Exposes your portfolio as a **Model Context Protocol** server so AI clients (e.g. Claude, IDE assistants) can query and act on your data. Configured across 8 tabs:

- **Server**: enable switch, name, version, title, website, description, instructions
- **Transports**: add/edit `webmcp`, `streamable-http`, `http`, `sse`, or `stdio` endpoints
- **Capabilities**: toggle tools / resources / prompts / logging / completions
- **Tools**: define custom tools — name, title, description, JSON input schema, and annotations (read-only, destructive, idempotent, open-world)
- **Resources**, **Prompts** (with typed arguments), and **Links**
- **Security**: a separate enable switch plus a bearer token you can generate, rotate, or revoke for write access (shown once)

A live JSON preview of the published `server-card.json` is shown before you save.

### API Reference

**Path**: Admin Panel → API Reference (`/admin/api-reference`)

A docs-only reference page with sticky side navigation covering:

- **API Token**: generate/revoke the blog automation token (interchangeable one-way with the MCP write token)
- **Create Blog Post** and **Upload Image** endpoint references
- **System Prompt**: the DB-tuned system prompt used by the AI Core
- **AI Hub Sections**: REST + MCP CRUD reference for the `/ai` page data
- **curl Examples** and general **Notes**

## 💾 Database Management

**Path**: Admin Panel → Database

### Database Export & System Backups

Allows one-click system backups exporting all database collections and uploaded image assets to a secure ZIP archive.
- **Cron Jobs**: Backs up cron task configurations while securely excluding environment variables (`webhookEnv`) and dynamic execution logs to prevent data/secret leaks.
- **Ads Configuration**: Backs up AdSense configurations, explicitly retrieving and saving all protected `select: false` encrypted client and slot keys.
- **Notification Configurations**: Backs up global push notification setups (ntfy, telegram, discord).
- **Other Collections**: Includes projects, blogs, gallery items, global config settings, and custom theme designs.

### Database Import & Restoration

Imports a JSON or ZIP archive to perform a hard reset and completely override database collections with imported data, immediately purging all in-memory caches. Supports full restorations for Cron jobs, Ads, and Notification configurations.

### Database Backup

**Automated Backups**:
- Daily backups at 2:00 AM
- Stored in `/backups` directory
- Last 7 backups retained

**Manual Backup**:
1. Click **"Create Backup"**
2. Backup saved with timestamp
3. Download or restore later

## 🗄️ Resources (Storage Manager)

**Path**: Admin Panel → Resources (`/admin/resources`)

Stat cards show **Total App Storage**, **Uploads On Disk**, **Database Content**, and **Unreferenced Uploads**.

- **Cleanup**: bulk-delete orphaned upload files (individually or all at once) with a reclaimed-space report
- **WebP Conversion**: convert legacy PNG/JPG originals and thumbnails to WebP, rewriting every database reference automatically

## 🩺 Server Health

**Path**: Admin Panel → Server Health (`/admin/health`)

Three tabs:

- **Resources**: live CPU, memory, and disk meters (auto-refresh every 5s), event-loop lag, database status/latency, heap/RSS usage, process & host uptime, Node version
- **Uptime**: monitors your deployment URLs plus any custom endpoints you add — up/down history strip, "Run check now", add/remove custom endpoints
- **AI Analyzer**: paste logs or a stack trace; it's combined with recent failed checks and security events and sent to the AI Core for a troubleshooting summary

## 🔒 Security Settings

**Path**: Admin Panel → Security

### Password Change

1. Enter **Current Password**
2. Enter **New Password** (min 12 characters)
3. Confirm **New Password**
4. Click **"Update Password"**

### Session Management

- View active sessions
- Revoke sessions
- Set session timeout (default: 24 hours)

### API Keys

- Regenerate **Blog API Key**
- Rotate **JWT Secret** (requires re-login)
- View API usage statistics

### Security Logs

- Login attempts
- Failed authentications
- Suspicious activities
- API requests

## 📊 Analytics Dashboard

**Path**: Admin Panel → Analytics

### Metrics

- **Page Views**: Total and per page
- **Popular Content**: Most viewed projects/blogs
- **Traffic Sources**: Referrers and direct visits
- **User Engagement**: Time on page, bounce rate

### Charts

- **Visitors Over Time**: Line chart
- **Content Performance**: Bar chart
- **Device Breakdown**: Pie chart
- **Geographic Distribution**: Map view

## 🛠️ Advanced Features

### Bulk Operations

**Bulk Edit Projects**:
1. Select multiple projects
2. Choose action:
   - Change status (publish/draft)
   - Add tags
   - Delete

**Bulk Edit Blogs**:
- Publish multiple drafts
- Update categories
- Archive old posts

### Content Scheduling

Schedule blog posts for future publication:
1. Set **Publish Date** in future
2. Save as published
3. Post goes live automatically

### Content Versioning

- Auto-save drafts every 30 seconds
- Restore previous versions
- View edit history

### Search and Filters

**Search Content**:
- Search by title, tags, description
- Full-text search in content
- Filter by status, date, category

**Advanced Filters**:
- Date range
- Status (draft/published)
- Tags (AND/OR logic)
- Author

## ⚙️ Settings — Section Stages & Preferences

**Path**: Admin Panel → Settings (`/admin/settings`)

- Pin a **Stable**, **Beta**, or **Alpha** badge to any nav section (all groups except Overview) via a per-item segmented control
- Saved as `adminSectionStages` (`{ "/admin/path": "beta" | "alpha" }`) on the config singleton
- Badges appear live in the sidebar as soon as you save; a dirty-state bar lets you Save or Reset before committing

## 📱 Mobile Admin Panel

The admin panel is fully responsive:

- **Mobile-optimized**: Touch-friendly interface
- **Responsive Tables**: Horizontal scroll on small screens
- **Mobile Editor**: Simplified Markdown editor
- **Quick Actions**: Swipe gestures for common tasks

## 🚀 Keyboard Shortcuts

- **Ctrl/Cmd + S**: Save current content
- **Ctrl/Cmd + P**: Preview
- **Ctrl/Cmd + B**: Bold text (in editor)
- **Ctrl/Cmd + I**: Italic text (in editor)
- **Ctrl/Cmd + K**: Insert link (in editor)
- **Esc**: Close modal/dialog

## 🔧 Troubleshooting

### Can't Login

1. Verify credentials in `.env` file
2. Clear browser cookies
3. Check JWT_SECRET is set
4. Restart application

### Changes Not Saving

1. Check database connection
2. Verify write permissions
3. Check browser console for errors
4. Try clearing cache

### Images Not Uploading

1. Check file size (max 5MB)
2. Verify file format (JPEG, PNG, WebP, HEIC)
3. Check storage space
4. Ensure upload directory has write permissions

## 📚 Additional Resources

- **[Admin Panel Manual](Admin-Panel-Manual)** - Detailed admin panel usage guide
- **[API Documentation](API-Documentation)** - API integration
- **[AI Neural Core](AI-Neural-Core)** - Generative features and AI governance
- **[Security Guide](Security-Guide)** - Security best practices

---

**[← Previous: Configuration](Configuration)** | **Next: [API Documentation](API-Documentation) →**