# 🚀 CardingCentral - Advanced Blog Platform

A next-gen educational blog platform for fraud prevention and scam awareness, built with modern web technologies and advanced admin features.

## ✨ Features

### 🌐 Public Blog
- **Category-based routing**: `/category/post-slug` URL structure
- **Dynamic category navigation**: Auto-populated from database
- **SEO optimized**: Meta tags, JSON-LD, Open Graph, Twitter cards
- **Sitemap & robots.txt**: Auto-generated for search engines
- **Responsive design**: Mobile-first, modern UI with TailwindCSS
- **Fast performance**: Vite bundling, image optimization

### 📝 Advanced Admin Dashboard
- **Next-gen post editor**: TipTap rich text + drag-and-drop blocks
- **Block types**: 13+ content block types (paragraph, heading, image, code, quote, info boxes, CTA, etc.)
- **DnD Kit ordering**: Drag-and-drop to reorder content blocks
- **Banner & thumbnail images**: With automatic optimization (WebP + JPG conversion)
- **Real-time SEO panel**: SEO score calculator, meta preview, keyword suggestions
- **Post lifecycle**: Draft → Preview → Schedule → Publish
- **Media library**: Organized image management with WebP optimization
- **Category management**: Create/edit/delete with SEO fields and custom colors
- **Settings panel**: Telegram integration configuration

### 🤖 Telegram Integration
- **Automated notifications**: Auto-post on publish
- **Rich formatting**: Title, excerpt, category, thumbnail, link
- **One-click setup**: Configure token and chat ID in admin
- **Test connection**: Verify bot is working

### 📊 Admin Analytics
- **Dashboard stats**: Total posts, published, drafts, views, categories
- **Post distribution chart**: Visual post status breakdown
- **Recent activity**: Quick access to latest posts
- **Quick actions**: One-click access to common tasks

## 🛠️ Tech Stack

### Frontend
- **React 18** - UI library
- **Vite** - Build tool (lightning fast)
- **TailwindCSS** - Utility-first styling
- **Framer Motion** - Smooth animations
- **TipTap v2** - Rich text editor
- **@dnd-kit** - Drag-and-drop
- **React Router v6** - Client-side routing
- **React Helmet Async** - SEO meta tags
- **Recharts** - Admin analytics charts

### Backend
- **Node.js + Express** - Server framework
- **SQLite3** - Database (lightweight, no server needed)
- **Multer + Sharp** - Image upload & optimization
- **JWT + bcryptjs** - Authentication
- **node-telegram-bot-api** - Telegram integration
- **CORS + Helmet** - Security headers

## 🚀 Getting Started

### Prerequisites
- Node.js v22+
- npm v10+
- Telegram bot token (optional, for notifications)

### Installation

#### 1️⃣ Install Dependencies

**Server:**
```bash
cd server
npm install
```

**Client:**
```bash
cd ../client
npm install
```

#### 2️⃣ Start the Server

```bash
cd server
npm start
```

Server runs on: **http://localhost:5000**

Seeded data:
- Admin user: `admin` / `admin123`
- Sample categories: Fraud Prevention, Card Security, Scam Detection, Recovery Guide, Industry News

#### 3️⃣ Start the Client (in a new terminal)

```bash
cd client
npm run dev
```

Client runs on: **http://localhost:3000**

## 📖 Usage

### 👤 Admin Login
1. Navigate to `http://localhost:3000/admin`
2. Username: `admin`
3. Password: `admin123`

### ✍️ Creating a Post
1. Click **"New Post"** on dashboard
2. **Enter title** (auto-generates URL slug)
3. **Select category**
4. **Add content** using drag-drop blocks:
   - Click **"Add Block"** button
   - Choose block type (paragraph, image, code, info, etc.)
   - Edit block content (drag handle to reorder)
5. **Upload banner** (hero image) and **thumbnail** (card preview)
6. **Optimize for SEO**:
   - Fill meta title (30-60 chars)
   - Add meta description (120-160 chars)
   - Add keywords (comma-separated)
   - Set OG image
7. **Save as draft** or **Publish**
   - Publish sends auto-notification to Telegram (if configured)

### 🗂️ Managing Categories
1. Go to **Admin → Categories**
2. Create categories (appears in public header automatically)
3. Add SEO title/description for category pages
4. Set category color

### 🖼️ Media Library
1. Go to **Admin → Media**
2. Upload images (auto-optimized to WebP + JPG)
3. Copy URL to use in posts or settings
4. Organize and delete as needed

### 🤖 Telegram Setup
1. Create bot with [@BotFather](https://t.me/botfather) on Telegram
2. Get bot token
3. Go to **Admin → Settings**
4. Enter bot token and chat ID
5. Click **"Test Connection"** to verify
6. Posts published after setup auto-notify the Telegram chat/group

### 🔍 SEO Features

**On every post:**
- Custom meta title & description
- Keywords & tags
- Open Graph image for social sharing
- Reading time auto-calculated
- View count tracking

**Site-wide:**
- Auto-generated `/sitemap.xml`
- `/robots.txt` (excludes /admin)
- Structured data (JSON-LD Article schema)
- Responsive mobile design

## 📁 Project Structure

```
cardingcentral/
├── server/                  # Node.js + Express backend
│   ├── db/
│   │   ├── database.js     # SQLite connection & helpers
│   │   └── schema.sql      # Database schema
│   ├── routes/             # API endpoints
│   │   ├── auth.js         # Admin login/verify
│   │   ├── posts.js        # Post CRUD + publish
│   │   ├── categories.js   # Category management
│   │   ├── media.js        # Image upload
│   │   └── settings.js     # Site settings & Telegram
│   ├── middleware/
│   │   ├── auth.js         # JWT authentication
│   │   └── upload.js       # Multer + Sharp image processing
│   ├── services/
│   │   ├── telegram.js     # Bot notifications
│   │   └── sitemap.js      # Sitemap generation
│   └── index.js            # Express app entry point
│
├── client/                 # React + Vite frontend
│   ├── src/
│   │   ├── pages/          # Public pages (Home, CategoryPage, PostPage)
│   │   ├── components/     # Shared components (Header, Footer, BlockRenderer)
│   │   ├── admin/
│   │   │   ├── pages/      # Admin pages (Dashboard, Editor, etc.)
│   │   │   └── components/ # Admin components (BlockEditor, SEOPanel, etc.)
│   │   ├── utils/
│   │   │   ├── api.js      # API client (axios)
│   │   │   └── seo.js      # SEO utilities
│   │   └── index.css       # TailwindCSS
│   ├── index.html          # HTML entry
│   ├── vite.config.js      # Vite config (with API proxy)
│   └── tailwind.config.js  # TailwindCSS config
│
└── uploads/                # Static image uploads
```

## 🔑 API Endpoints

### Auth
- `POST /api/auth/login` - Admin login
- `POST /api/auth/verify` - Verify token

### Posts
- `GET /api/posts` - Get published posts (paginated)
- `GET /api/posts/:categorySlug/:postSlug` - Get single post
- `POST /api/posts` - Create post (admin)
- `PUT /api/posts/:id` - Update post (admin)
- `POST /api/posts/:id/publish` - Publish + Telegram notify (admin)
- `DELETE /api/posts/:id` - Delete post (admin)
- `GET /api/posts/admin/all` - All posts with statuses (admin)

### Categories
- `GET /api/categories` - All categories
- `GET /api/categories/:slug` - Category details
- `POST /api/categories` - Create (admin)
- `PUT /api/categories/:id` - Update (admin)
- `DELETE /api/categories/:id` - Delete (admin)

### Media
- `GET /api/media` - List uploads (admin)
- `POST /api/media/upload` - Upload image (admin)
- `PUT /api/media/:id` - Update metadata (admin)
- `DELETE /api/media/:id` - Delete (admin)

### Settings
- `GET /api/settings` - Get all settings (admin)
- `PUT /api/settings/:key` - Update setting (admin)
- `POST /api/settings/telegram/test` - Test bot connection (admin)

### SEO
- `GET /sitemap.xml` - Sitemap for search engines
- `GET /robots.txt` - Robots instructions

## 🗄️ Database

SQLite database with tables:
- `admins` - Admin users
- `categories` - Post categories
- `posts` - Blog posts (content stored as JSON blocks)
- `post_blocks` - DnD-ordered content blocks
- `media` - Uploaded images
- `tags` - Post tags
- `post_tags` - Many-to-many relationship
- `settings` - Key-value configuration store

## 🌐 Deployment

### Frontend (Netlify/Vercel)
```bash
cd client
npm run build
# Deploy dist/ folder
```

### Backend (Heroku/Railway/Render)
```bash
cd server
npm start
# Set environment variables:
# - NODE_ENV=production
# - JWT_SECRET=your-secret
# - SITE_URL=https://your-domain.com
```

## 🔒 Security

- JWT token-based authentication
- Password hashing (bcryptjs)
- CORS protection (whitelisted origins)
- Helmet security headers
- Input validation (express-validator)
- No sensitive data in logs
- File upload validation (only images)

## 🚀 Performance

- **Images**: Automatic WebP optimization + JPG fallback
- **Bundling**: Vite (sub-second HMR)
- **CSS**: TailwindCSS PurgeCSS (minimal production)
- **Caching**: Browser caching headers on static assets
- **Database**: Indexed queries for fast lookups
- **SEO**: Structured data reduces crawl time

## 📝 Content Best Practices

### For Posts
- **Title**: 30-60 characters (SEO)
- **Excerpt**: 120-160 characters (preview)
- **Content**: Use block types appropriately (not everything in paragraph)
- **Images**: Use WebP where possible
- **Meta**: Fill title, description, keywords
- **Links**: Use meaningful anchor text

### For Categories
- **Name**: 2-4 words
- **Description**: Brief, keyword-rich
- **Color**: Distinct for visual hierarchy

## 🐛 Troubleshooting

### Server won't start
```bash
# Check port 5000 is available
# Or change PORT in server/index.js
```

### Images not optimizing
```bash
# Check Sharp library
npm install --save-optional sharp
```

### Telegram not sending
1. Verify bot token is correct
2. Check chat ID (should be negative for groups)
3. Test connection in Settings page
4. Check bot has permission to post

### CORS errors
- Frontend must be on localhost:3000 or add origin to server CORS

## 📚 Learning Resources

- [TipTap Editor Docs](https://tiptap.dev)
- [DnD Kit](https://docs.dnd-kit.com)
- [React Router](https://reactrouter.com)
- [Express.js](https://expressjs.com)
- [TailwindCSS](https://tailwindcss.com)

## 🎯 Next Steps

1. ✅ Install dependencies
2. ✅ Start server & client
3. 📝 Create your first post
4. 🗂️ Add categories
5. 🤖 Setup Telegram (optional)
6. 🚀 Deploy to production

## 📞 Support

For issues or questions:
1. Check the troubleshooting section
2. Review API docs above
3. Check browser console for errors
4. Check server logs for backend errors

## 📄 License

Built for educational purposes. Modify and redistribute as needed.

---

**Happy blogging! 🚀**
