Overview

File: 01-overview.md

Loading documentation...

# CreatorContent.net - Project Overview

## Project Description

CreatorContent.net is a comprehensive content creation and management platform designed for creators (musicians, podcasters, bloggers, etc.) to build and manage their online presence. The platform provides tools for content creation, public profile management, monetization, and audience engagement.

## Core Features

- **Public Profiles & Pages**: Customizable public-facing profiles with page builder system
- **Podcast Management**: Complete podcast workflow (creation, episodes, RSS feeds, transcriptions)
- **Blog System**: Multi-blog support with posts, categories, and tags
- **Event Management**: Events and event lists with calendar views
- **Media Library**: Centralized media management (images, audio, video)
- **Studio System**: Professional audio editing with FFmpeg integration
- **Polls & Surveys**: Interactive audience engagement tools
- **Comments & Moderation**: Comment system with moderation tools
- **Subscriptions**: Stripe-powered subscription plans with Laravel Cashier
- **Token System**: Flexible token-based feature access (SMS, email, transcription)
- **Notification System**: Email and SMS notifications for audiences
- **Custom Domains**: Custom domain support for public profiles
- **Admin Dashboard**: Comprehensive admin interface for platform management

## Tech Stack

### Backend
- **Framework**: Laravel 12.0
- **PHP**: 8.2+
- **Database**: MySQL/PostgreSQL (configurable)
- **Authentication**: Laravel Sanctum (token-based API authentication)
- **Payment Processing**: Laravel Cashier (Stripe integration)
- **Queue System**: Laravel Queues (for background jobs)
- **File Storage**: Laravel Storage (local/S3 compatible)

### Frontend
- **JavaScript**: Vanilla ES6+ (no framework dependencies)
- **CSS Framework**: Tailwind CSS 4.0
- **Build Tool**: Vite 6.2
- **UI Components**: Custom components with Tailwind
- **Icons**: Font Awesome 6.4

### Third-Party Integrations
- **OpenAI**: Audio transcription services (`openai-php/client`)
- **Twilio**: SMS notifications (`twilio/sdk`)
- **Stripe**: Payment processing (via Laravel Cashier)
- **Image Processing**: Intervention Image 3.11
- **QR Codes**: SimpleSoftwareIO Simple QRCode

### Development Tools
- **Code Quality**: Laravel Pint (PHP CS Fixer)
- **Testing**: PHPUnit 11.5
- **Logging**: Laravel Pail (real-time log viewing)
- **Faker**: FakerPHP for test data generation

## Architecture Overview

### Application Structure

```
creatorcontent.net/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Auth/           # Authentication controllers
│   │   │   ├── Dashboard/      # Dashboard feature controllers
│   │   │   ├── Admin/           # Admin panel controllers
│   │   │   └── ...              # Other controllers
│   │   ├── Middleware/          # Custom middleware (TokenAuth, ResolveDomain)
│   │   └── Requests/            # Form request validation
│   ├── Models/                  # Eloquent models (50+ models)
│   ├── Services/                # Business logic services
│   └── Providers/               # Service providers
├── database/
│   ├── migrations/              # Database migrations
│   ├── seeders/                 # Database seeders
│   └── factories/               # Model factories
├── resources/
│   ├── views/
│   │   ├── layouts/             # Blade layouts (app.blade.php with API methods)
│   │   ├── dashboard/           # Dashboard views
│   │   ├── public/              # Public-facing views
│   │   │   ├── profile/         # Public profile pages
│   │   │   └── page/            # Public page views
│   │   ├── sections/            # Reusable section components
│   │   └── templates/           # Base templates for profiles/pages
│   └── js/                      # JavaScript files (minimal, most in Blade)
├── routes/
│   ├── web.php                  # Web routes
│   ├── api.php                  # API routes (comprehensive REST API)
│   └── console.php              # Artisan commands
├── public/                      # Public web root
└── storage/                     # File storage
```

### Authentication Architecture

The application uses **Laravel Sanctum** with a custom token-based authentication system:

- Tokens stored as cookies (`auth_token`) for session-like behavior
- Token expiration: 7 days
- Middleware: `TokenAuth` validates tokens on API requests
- Frontend API methods automatically include credentials via `credentials: 'include'`

See `resources/views/layouts/app.blade.php` for all available API helper methods.

### Domain Resolution System

The platform supports multiple domain access patterns:

- **Main Domain**: `creatorcontent.net` (main application)
- **Subdomain**: `admin.creatorcontent.net` (admin panel)
- **Custom Domains**: User-owned domains pointing to profiles
- **Profile Slugs**: `creatorcontent.net/{slug}` (public profiles)

The `ResolveDomain` middleware handles domain resolution and routing.

### API Architecture

- **RESTful API**: Standard CRUD operations
- **Authentication**: Token-based via Sanctum
- **Response Format**: Consistent JSON responses with `success`, `message`, and `data` fields
- **Error Handling**: Standardized error responses with validation errors
- **Rate Limiting**: Laravel rate limiting on API routes

## Directory Structure

### Key Directories

- `app/Models/`: 50+ Eloquent models representing all data entities
- `app/Http/Controllers/Dashboard/`: Feature-specific dashboard controllers
- `app/Http/Controllers/Admin/`: Admin panel controllers
- `resources/views/sections/`: Reusable Blade section components
- `resources/views/templates/`: Base templates for profiles and pages
- `routes/api.php`: 600+ lines of API endpoint definitions

## Setup Instructions

### Prerequisites

- PHP 8.2 or higher
- Composer 2.x
- Node.js 18+ and npm
- MySQL 8.0+ or PostgreSQL 13+
- FFmpeg (for Studio system)
- Redis (optional, for queues/caching)

### Installation Steps

1. **Clone the repository** (if applicable) or navigate to project directory

2. **Install PHP dependencies**:
   ```bash
   composer install
   ```

3. **Install JavaScript dependencies**:
   ```bash
   npm install
   ```

4. **Configure environment**:
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```
   
   Edit `.env` and configure:
   - Database credentials
   - App URL
   - Stripe keys (STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET)
   - Twilio credentials (TWILIO_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER)
   - OpenAI API key (OPENAI_API_KEY)
   - Mail configuration

5. **Run database migrations**:
   ```bash
   php artisan migrate
   ```

6. **Seed database** (optional, for development):
   ```bash
   php artisan db:seed
   ```

7. **Link storage**:
   ```bash
   php artisan storage:link
   ```

8. **Build assets**:
   ```bash
   npm run build
   ```

9. **Start development server**:
   ```bash
   php artisan serve
   ```

Or use the dev script that runs multiple services:
   ```bash
   composer run dev
   ```
   This starts:
   - Laravel server
   - Queue worker
   - Log viewer (Pail)
   - Vite dev server

### Environment Variables

Required environment variables:

```env
# Application
APP_NAME=CreatorContent.net
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=creatorcontent
DB_USERNAME=root
DB_PASSWORD=

# Stripe
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Twilio
TWILIO_SID=
TWILIO_AUTH_TOKEN=
TWILIO_PHONE_NUMBER=

# OpenAI
OPENAI_API_KEY=

# Mail
MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
```

### Post-Installation

1. **Configure Stripe Webhooks**:
   - Point to: `{APP_URL}/api/webhook/stripe`
   - Required events: See `docs/stripe-webhook-events.md`

2. **Set up Queue Worker** (for background jobs):
   ```bash
   php artisan queue:work
   ```

3. **Verify Setup**:
   - Visit `{APP_URL}/login`
   - Create a test user
   - Access dashboard

## Development Workflow

### Running Locally

```bash
# Start all development services
composer run dev

# Or individually:
php artisan serve              # Web server
php artisan queue:listen       # Queue worker
php artisan pail               # Log viewer
npm run dev                    # Vite dev server
```

### Code Quality

```bash
# Format PHP code
php artisan pint

# Run tests
php artisan test
# or
composer run test
```

### API Development

All API calls should use the helper methods defined in `resources/views/layouts/app.blade.php`:
- `apiCall()`, `apiGet()`, `apiPost()`, `apiPut()`, `apiPatch()`, `apiDelete()`
- `apiFileUpload()` for file uploads
- `uploadFileAndCreateMedia()` for media creation

See the repository rules for complete API method documentation.

## Database Schema

The application uses 50+ database tables including:
- User management (users, login_tokens, personal_access_tokens)
- Content (podcasts, episodes, blogs, posts, events, polls, surveys)
- Profiles (public_profiles, public_pages, profile_sections)
- Media (media, media_clips, media_lists)
- Subscriptions (plans, subscriptions, subscription_payments)
- Tokens (token_packages, token_purchases, token_usage_logs)
- Studio (studio_projects, studio_project_assets, etc.)
- And many more...

See `docs/04-database-schema.md` for complete schema documentation.

## Additional Resources

- **API Reference**: See `docs/03-api-reference.md`
- **Authentication**: See `docs/02-authentication.md`
- **Frontend Architecture**: See `docs/05-frontend-architecture.md`
- **Feature Documentation**: See docs `06-17` for individual features

## Support

For development questions or issues, refer to:
- Individual feature documentation in the `/docs` folder
- Code comments and docblocks
- Laravel documentation: https://laravel.com/docs

Overview

Overview

📝 Page Notes

Add New Note