placebo.mk/ADMINISTRATOR_GUIDE.md

Administrator Guide - Placebo.mk

Overview

Placebo.mk is a Macedonian news site with a sarcastic tone. This guide covers system administration, user management, and technical operations.

System Architecture

• Frontend: TanStack (React 19, Query, Router) + Vite + Tailwind CSS
• Backend: NestJS + TypeORM + SQLite
• CMS: Strapi for content management
• Database: SQLite with TypeORM entities

Environment Setup

Backend Configuration

cd backend
cp .env.example .env
# Configure environment variables:
# DATABASE_PATH=./data/app.db
# PORT=3000
# NODE_ENV=development
npm install
npm run start:dev

Frontend Configuration

cd frontend
cp .env.example .env
# Configure environment variables:
# VITE_API_URL=http://localhost:3000
npm install
npm run dev

CMS (Strapi) Configuration

cd cms/cms
cp .env.example .env
# Configure Strapi environment variables:
# DATABASE_CLIENT=sqlite
# DATABASE_FILENAME=./data/app.db
# API_TOKEN_SALT=
# ADMIN_JWT_SECRET=
npm run develop

Database Management

Entities Overview

• Articles: News articles with status (draft/published/archived)
• Authors: Writer profiles with permissions
• Categories: Hierarchical content organization
• Live Blogs: Real-time event coverage
• Live Blog Updates: Individual updates within live blogs

Database Operations

# Run migrations (if implemented)
npm run migration:run

# Check database schema
npm run schema:sync

# Backup database
cp backend/data/app.db backend/data/backup-$(date +%Y%m%d).db

User Management

Author Management

Authors are stored in the authors table with:

• Basic profile (name, bio, avatar)
• Unique slug for URLs
• isActive flag for permissions
• Relations to articles and live blogs

CMS User Roles

1. Super Admin: Full system access
2. Admin: Content and user management
3. Editor: Content creation and editing
4. Author: Limited to assigned content

Creating New Authors

INSERT INTO authors (id, name, slug, bio, avatar, isActive, createdAt, updatedAt)
VALUES (
  uuid(),
  'Author Name',
  'author-slug',
  'Author bio',
  'avatar-url.jpg',
  true,
  datetime('now'),
  datetime('now')
);

Content Management

Article Workflow

1. Draft: Initial creation phase
2. Published: Publicly visible
3. Archived: No longer public but retained

Live Blog Management

Live blogs support real-time updates:

• Draft: Preparation phase
• Live: Active event coverage
• Ended: Coverage complete
• Archived: Historical reference

API Management

Available Endpoints

GET    /api/v1/articles              # List articles
GET    /api/v1/articles/:id          # Get single article
GET    /api/v1/articles/slug/:slug   # Get article by slug
POST   /api/v1/articles              # Create article
PUT    /api/v1/articles/:id          # Update article
DELETE /api/v1/articles/:id          # Delete article

GET    /api/v1/live-blogs            # List live blogs
GET    /api/v1/live-blogs/:id        # Get live blog
POST   /api/v1/live-blogs            # Create live blog
PUT    /api/v1/live-blogs/:id        # Update live blog

GET    /api/v1/authors                # List authors
GET    /api/v1/categories             # List categories

API Authentication

Configure JWT tokens for secure API access:

// In .env
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h

CMS Administration

Strapi Admin Panel

Access at: http://localhost:1337/admin

Content Types Configuration

Articles support:

• Rich text content
• Multiple media files (images, files, videos, audio)
• Featured images
• Author attribution

Media Management

• Upload limits configured in Strapi settings
• Image optimization handled automatically
• File organization in /uploads directory

Performance Monitoring

Backend Monitoring

# Check application logs
npm run start:prod

# Monitor performance
npm run start:prod -- --inspect

Frontend Performance

# Build for production
cd frontend
npm run build

# Analyze bundle size
npm run build:analyze

Security Considerations

Authentication

• Implement proper JWT handling
• Use secure password hashing
• Set appropriate CORS policies

Data Protection

• Regular database backups
• Environment variable protection
• Input validation and sanitization

CMS Security

• Regular Strapi updates
• Role-based access control
• Media file scanning

Backup and Recovery

Automated Backups

# Create backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p backups
cp backend/data/app.db backups/app_$DATE.db
tar -czf backups/uploads_$DATE.tar.gz cms/cms/public/uploads/

Recovery Process

1. Stop all services
2. Restore database from backup
3. Restore media files
4. Restart services
5. Verify functionality

Troubleshooting

Common Issues

Database Connection Errors

# Check database file exists
ls -la backend/data/app.db

# Verify permissions
chmod 664 backend/data/app.db

Strapi Admin Access

# Reset admin password
npm run strapi admin:reset-password

Frontend Build Issues

# Clear cache
rm -rf node_modules package-lock.json
npm install

# Check environment variables
cat .env

Maintenance Tasks

Daily

• Monitor system logs
• Check backup completion
• Review performance metrics

Weekly

• Update dependencies
• Review content moderation queue
• Security scan

Monthly

• Database maintenance
• Archive old content
• Performance optimization review

Scaling Considerations

Database Scaling

• Consider PostgreSQL for high traffic
• Implement read replicas
• Optimize queries and indexes

CDN Integration

• Configure CDN for static assets
• Optimize image delivery
• Implement caching strategies

Monitoring Setup

• Application performance monitoring
• Error tracking and alerting
• User analytics and reporting