# ChatBud PHP Backend - Documentation Index

Welcome to ChatBud PHP Backend! This document is your guide to all documentation.

## Quick Start

**New to ChatBud?** Start here:

1. [Installation](README_COMPLETE.md#installation) - Set up the project
2. [Database Setup](DATABASE_SETUP.md) - Create and configure database
3. [Email Configuration](EMAIL_SETUP.md) - Set up email service
4. [API Usage](API_DOCUMENTATION.md) - Start using the API

## Documentation Files

### 📖 Main Documentation

- **[README_COMPLETE.md](README_COMPLETE.md)** - Full project documentation
  - Features overview
  - Tech stack details
  - Project structure
  - Installation guide
  - Development guide
  - Deployment checklist
  - Troubleshooting

- **[API_DOCUMENTATION.md](API_DOCUMENTATION.md)** - REST API Reference
  - Authentication
  - All 25+ endpoints
  - Request/response examples
  - Status codes
  - Error handling
  - Pagination
  - curl/Postman examples

- **[DATABASE_SETUP.md](DATABASE_SETUP.md)** - Database Configuration
  - MySQL setup
  - PostgreSQL setup
  - Schema verification
  - Backup & restore
  - Maintenance
  - Performance optimization
  - Troubleshooting

- **[EMAIL_SETUP.md](EMAIL_SETUP.md)** - Email & Notifications
  - Email providers (SMTP, SendGrid, Mailgun)
  - Configuration guides
  - Email types
  - Custom templates
  - Notification preferences
  - Testing & troubleshooting

- **[INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)** - System Architecture
  - Component architecture diagram
  - Request flow examples
  - Model dependencies
  - Database integration
  - Performance considerations
  - Testing strategies

### 🛠️ Setup Files

- **[setup.sh](setup.sh)** - Automated setup script
  ```bash
  bash setup.sh
  ```

- **[.env.example](.env.example)** - Environment configuration template
  - Copy to `.env` and update
  - All available settings
  - Comments for each option

- **[test_db.php](test_db.php)** - Database connection test
  ```bash
  php test_db.php
  ```

- **[test_email.php](test_email.php)** - Email service test
  ```bash
  php test_email.php
  ```

### 📁 Source Code

**Application Layers:**

```
src/lib/
├── config.php              - Configuration & autoloading
├── utils.php               - Utility functions
├── Router.php              - URL routing
├── Database.php            - Database abstraction layer
├── API.php                 - REST API handler (25+ endpoints)
├── Auth.php                - Authentication & sessions
├── User.php                - User model
├── Post.php                - Post model
├── Notification.php        - Notifications
├── DirectMessage.php       - Direct messaging
├── EmailService.php        - Email sending
└── FileUpload.php          - File upload handler
```

**Frontend Templates:**

```
src/templates/
├── routes/                 - Page templates
│   ├── home.php
│   ├── feed.php
│   ├── profile.php
│   └── ... (11 total)
└── emails/                 - Email templates (to create)
```

**Public:**

```
public/
├── index.php               - Web entry point
├── api.php                 - API entry point
├── .htaccess               - Apache URL rewriting
└── uploads/                - User-uploaded files
```

## Use Case Examples

### For Frontend Developers

👉 **Need API documentation?**
- Read [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
- Try example curl commands
- Test in Postman with provided examples

### For Backend Developers

👉 **Need to add a new feature?**
1. Check [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) for architecture
2. Create model in `src/lib/YourModel.php`
3. Add endpoint in `src/lib/API.php`
4. Update database schema if needed
5. Create email template if needed

👉 **Need to modify a model?**
- Look at existing model structure: `src/lib/User.php`
- Models use `Database::getInstance()`
- Return JSON-serializable data

### For DevOps/Deployment

👉 **Setting up production?**
1. Follow [Installation](README_COMPLETE.md#installation)
2. Follow [Database Setup](DATABASE_SETUP.md)
3. Follow [Email Setup](EMAIL_SETUP.md)
4. Check [Production Checklist](README_COMPLETE.md#production-checklist)
5. Run security audit

### For QA/Testing

👉 **Testing the API?**
1. Run `php test_db.php` - Database test
2. Run `php test_email.php` - Email test
3. Use [API_DOCUMENTATION.md](API_DOCUMENTATION.md) - Test endpoints
4. Create Postman collection from examples

## Database Schema

**13 Tables:**
- `users` - User accounts
- `user_sessions` - Active sessions
- `posts` - User posts
- `post_media` - Images, videos for posts
- `comments` - Comments on posts
- `likes` - Post/comment likes
- `follows` - Follow relationships
- `notifications` - User notifications
- `direct_messages` - Direct messages
- `password_reset_tokens` - Password reset
- `email_verification_tokens` - Email verification
- `blocks` - Blocked users
- `user_presence` - Online status

See [database.sql](database.sql) for full schema.

## API Endpoints Summary

**Auth** (4 endpoints)
- POST `/auth/register` - Register user
- POST `/auth/login` - Login
- POST `/auth/logout` - Logout
- POST `/auth/refresh` - Refresh token

**Users** (7 endpoints)
- GET `/users/:id` - Get user
- PUT `/users/:id` - Update user
- GET `/users/:id/posts` - Get user's posts
- GET `/users/:id/followers` - Get followers
- GET `/users/:id/following` - Get following
- POST `/users/:id/follow` - Follow user
- DELETE `/users/:id/follow` - Unfollow

**Posts** (7 endpoints)
- GET `/posts` - Get feed/trending
- GET `/posts/:id` - Get single post
- POST `/posts` - Create post
- PUT `/posts/:id` - Update post
- DELETE `/posts/:id` - Delete post
- POST `/posts/:id/like` - Like post
- DELETE `/posts/:id/like` - Unlike post

**Comments** (2 endpoints)
- GET `/posts/:id/comments` - Get comments
- POST `/posts/:id/comments` - Add comment

**Media** (1 endpoint)
- POST `/upload` - Upload file

**Feed** (1 endpoint)
- GET `/feed` - Get user's feed

Total: **25+ endpoints**

## Configuration Checklist

### Before Going Live

- [ ] Database configured and tested
- [ ] Email service configured and tested
- [ ] .env file created with all values
- [ ] File upload directory permissions set
- [ ] HTTPS/SSL enabled
- [ ] Database backups configured
- [ ] Error logging configured
- [ ] Monitoring setup
- [ ] Security headers enabled
- [ ] CORS configured if needed

### Development

- [ ] Code follows PSR-2 standards
- [ ] All SQL uses prepared statements
- [ ] Passwords hashed with Argon2ID
- [ ] Error logging implemented
- [ ] API returns proper HTTP status codes
- [ ] Authentication checks on protected routes
- [ ] Authorization checks on user resources

### Production

- [ ] APP_DEBUG=false in .env
- [ ] Error display disabled
- [ ] Error logging to file enabled
- [ ] Database replication/backup
- [ ] Rate limiting enabled
- [ ] WAF/DDoS protection
- [ ] CDN for static files
- [ ] Email provider failover
- [ ] Monitoring alerts configured

## Common Tasks

### How to...

**Add a new API endpoint?**
1. Add route to `API::getRoutes()`
2. Create handler method in `API` class
3. Add auth check if needed
4. Return JSON response

**Create a new model?**
1. Create `src/lib/YourModel.php`
2. Extend with Database methods
3. Use `$this->db = Database::getInstance()`
4. Return data from methods

**Send a notification?**
1. Use `Notification::create()`
2. Specify type (follow, like, comment, mention)
3. Email automatically sent based on preferences

**Customize email template?**
1. Create `src/templates/emails/your-email.php`
2. Use `EmailService::sendTemplate()`
3. Pass data to template

**Upload a file?**
1. POST to `/api/v1/upload` with multipart/form-data
2. Get URL from response
3. Store in database

## Troubleshooting

**Database not connecting?**
→ See [DATABASE_SETUP.md](DATABASE_SETUP.md#troubleshooting)

**Emails not sending?**
→ See [EMAIL_SETUP.md](EMAIL_SETUP.md#troubleshooting)

**API returning 404?**
→ Check Apache mod_rewrite enabled and .htaccess in place

**File upload failing?**
→ Check public/uploads permissions (755)

**Session/Auth issues?**
→ Check user_sessions table exists, user is verified

## Support Resources

- **GitHub Issues:** Report bugs and request features
- **Email:** support@chatbud.com
- **Docs:** Full documentation in README_COMPLETE.md
- **Examples:** curl examples in API_DOCUMENTATION.md

## File Sizes

- **PHP files:** ~400KB total
- **Database schema:** ~50KB
- **Documentation:** ~200KB
- **Total codebase:** ~650KB (excluding uploads)

## Version Info

- **PHP Version:** 7.4+
- **Database:** MySQL 5.7+ or PostgreSQL 10+
- **API Version:** v1
- **Release Date:** 2026-08-18

## Next Steps

1. **Installation:** Follow [README_COMPLETE.md](README_COMPLETE.md#installation)
2. **Configuration:** Set up [Database](DATABASE_SETUP.md) and [Email](EMAIL_SETUP.md)
3. **Testing:** Run test scripts and try API examples
4. **Development:** Create custom features following patterns
5. **Deployment:** Follow production checklist before going live

---

**Happy coding! 🚀**

Need help? Check the documentation index above or contact support@chatbud.com