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
```bash
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
```bash
cd frontend
cp .env.example .env
# Configure environment variables:
# VITE_API_URL=http://localhost:3000
npm install
npm run dev
```

### CMS (Strapi) Configuration
```bash
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
```bash
# 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
```sql
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:
```typescript
// 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
```bash
# Check application logs
npm run start:prod

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

### Frontend Performance
```bash
# 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
```bash
# 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
```bash
# Check database file exists
ls -la backend/data/app.db

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

#### Strapi Admin Access
```bash
# Reset admin password
npm run strapi admin:reset-password
```

#### Frontend Build Issues
```bash
# 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