Article Review System - Modernization Project

Complete modernization of the Article Review application from monolithic PHP to modern Laravel 11 API + Vue 3 Frontend.

Status: Phase 1 Backend (85% Complete)
Timeline: Weeks 1-2 of 4-week Phase 1
Start Date: 2026-06-22
Target Completion: 2026-08-31

---

Project Overview

This repository contains the modernized Article Review System, split into:

• Backend: Laravel 11 API with comprehensive testing
• Frontend: Vue 3 + TypeScript (Phase 2)
• Infrastructure: Docker Compose setup

Current Status

Phase	Component	Status	Timeline
1	Backend (Laravel 11)	85% Complete ✅	Weeks 1-4
2	Frontend (Vue 3)	Not Started ⏳	Weeks 5-6
3	UI Components	Not Started ⏳	Weeks 7-9
4	Testing & QA	Not Started ⏳	Weeks 9-10
5	Deployment	Not Started ⏳	Weeks 10-11

---

Quick Start

Local Development

# Backend setup
cd backend
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve

Backend available at http://localhost:8000/api/v1/

Docker Development

# From project root
docker-compose up --build

# Run migrations
docker-compose exec laravel php artisan migrate

# Run tests
docker-compose exec laravel ./vendor/bin/pest

Backend available at http://localhost:8080/api/v1/

---

Documentation Guide

Phase 1 Backend Documentation

Document	Purpose
MODERNIZATION.md	Strategic modernization plan (10-week roadmap)
PHASE_1_SPEC.md	Detailed Phase 1 technical specification
PHASE_1_COMPLETION_SUMMARY.md	Current status and deliverables
BACKEND_README.md	Backend setup, usage, and development guide
API_DOCUMENTATION.md	Complete API endpoint reference
backend/ARCHITECTURE.md	Backend architecture and design
PROGRESS.md	Weekly progress tracking

Start Here

1. Read MODERNIZATION.md for overall strategy
2. Read PHASE_1_COMPLETION_SUMMARY.md for current status
3. Follow BACKEND_README.md for local setup
4. Reference API_DOCUMENTATION.md for API usage

---

Backend Architecture

HTTP Request
    ↓
Nginx (Port 8080)
    ↓
Laravel 11 (PHP-FPM)
├── Controllers (4)
├── Services (4)
├── Models (4)
├── Migrations (4)
└── Tests (38+)
    ↓
MySQL 8.0 Database

Core Components

Models (app/Models/)

• Article - Status: new, ignored, downloaded, saved
• Performer - Status: normal, ignored, highlighted
• Keyword - Status: normal, hidden, highlighted, ignored
• Site - Status: normal, highlighted, ignored

Controllers (app/Http/Controllers/)

• ArticleController - CRUD + getNext
• PerformerController - CRUD
• KeywordController - CRUD
• SiteController - CRUD

Services (app/Services/)

• ArticleParsingService - RSS parsing
• OmgApiService - NZB search/download
• StashService - GraphQL integration
• DownloadService - File management

---

API Endpoints

All endpoints are at http://localhost:8080/api/v1/

Articles (7 endpoints)

GET    /articles              # List all
POST   /articles              # Create
GET    /articles/{id}         # Get one
PATCH  /articles/{id}/status  # Update status
DELETE /articles/{id}         # Delete
GET    /articles/next         # Get next new

Performers (5 endpoints)

GET    /performers      # List all
POST   /performers      # Create
GET    /performers/{id} # Get one
PATCH  /performers/{id} # Update
DELETE /performers/{id} # Delete

Keywords (5 endpoints)

GET    /keywords      # List all
POST   /keywords      # Create
GET    /keywords/{id} # Get one
PATCH  /keywords/{id} # Update
DELETE /keywords/{id} # Delete

Sites (5 endpoints)

GET    /sites      # List all
POST   /sites      # Create
GET    /sites/{id} # Get one
PATCH  /sites/{id} # Update
DELETE /sites/{id} # Delete

Total: 22 Endpoints

---

Development Commands

Setup

cd backend
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate

Testing

# Run all tests
./vendor/bin/pest

# Run with coverage
./vendor/bin/pest --coverage

# Run specific suite
./vendor/bin/pest --group=feature
./vendor/bin/pest --group=unit

# Run specific test file
./vendor/bin/pest tests/Feature/ArticleControllerTest.php

Database

# Run migrations
php artisan migrate

# Fresh migrations
php artisan migrate:fresh

# Rollback
php artisan migrate:rollback

# Seed database
php artisan db:seed

Development

# Start dev server
php artisan serve

# Interactive shell
php artisan tinker

# Create migration
php artisan make:migration table_name

# Create model
php artisan make:model ModelName

Docker

# Build and start
docker-compose up --build

# Run command in container
docker-compose exec laravel php artisan migrate

# View logs
docker-compose logs -f laravel

# Stop containers
docker-compose down

---

File Structure

article-review/
├── backend/                    # Laravel 11 Application
│   ├── app/
│   │   ├── Http/Controllers/   # API Controllers (4)
│   │   ├── Http/Requests/      # Validation (8)
│   │   ├── Http/Resources/     # Response Format (5)
│   │   ├── Http/Middleware/    # HTTP Middleware
│   │   ├── Models/             # Eloquent Models (4)
│   │   ├── Services/           # Business Logic (4)
│   │   └── Exceptions/         # Exception Handling
│   ├── database/
│   │   ├── migrations/         # Database Migrations (4)
│   │   └── factories/          # Test Factories (4)
│   ├── routes/
│   │   └── api.php             # API Routes
│   ├── tests/
│   │   ├── Feature/            # Controller Tests (6)
│   │   ├── Unit/               # Service & Model Tests (10)
│   │   └── TestCase.php        # Base Test Class
│   ├── config/                 # Configuration
│   ├── storage/                # Application Storage
│   ├── bootstrap/              # Bootstrap Files
│   ├── public/                 # Public Entry Point
│   ├── composer.json           # Dependencies
│   ├── ARCHITECTURE.md         # Architecture Guide
│   └── .env.example            # Environment Template
│
├── docker/                     # Docker Configuration
│   ├── Dockerfile.laravel      # Laravel Container
│   ├── nginx/conf.d/           # Nginx Configuration
│   └── mysql/                  # Database Seeds
│
├── MODERNIZATION.md            # 10-Week Plan
├── PHASE_1_SPEC.md             # Phase 1 Specification
├── PHASE_1_COMPLETION_SUMMARY.md
├── PROGRESS.md                 # Status Tracking
├── API_DOCUMENTATION.md        # API Reference
├── BACKEND_README.md           # Backend Guide
├── docker-compose.yml          # Container Orchestration
└── README.md                   # This File

---

Phase 1 Completion Status

Completed (✅)

• Laravel 11 project structure
• 4 Eloquent models with full functionality
• 4 database migrations (reversible)
• 4 model factories for testing
• 4 API controllers with CRUD
• 8 form request validators
• 4 API resource classes
• 22 REST API endpoints
• 4 business logic services
• Exception handling & middleware
• 38+ test cases (Feature + Unit)
• Docker configuration
• Comprehensive documentation (4 files)

In Progress (⏳)

• Docker build and verification
• Test execution and coverage report
• Integration testing
• Performance baseline

Not Started (Future)

• Frontend (Vue 3) - Phase 2
• UI Components - Phase 3
• Advanced Testing - Phase 4
• Deployment & CI/CD - Phase 5

---

Testing

Test Statistics

• Total Tests: 38+
• Feature Tests: 25+ (Controllers, Validation)
• Unit Tests: 10+ (Services, Models)
• Coverage Target: 80%+

Test Files

• tests/Feature/ArticleControllerTest.php
• tests/Feature/ArticleValidationTest.php
• tests/Feature/PerformerControllerTest.php
• tests/Feature/PerformerValidationTest.php
• tests/Feature/KeywordControllerTest.php
• tests/Feature/SiteControllerTest.php
• tests/Unit/Services/ArticleParsingServiceTest.php
• tests/Unit/Services/DownloadServiceTest.php
• tests/Unit/Models/ArticleTest.php
• tests/Unit/Models/PerformerTest.php

Running Tests

cd backend
./vendor/bin/pest
./vendor/bin/pest --coverage
./vendor/bin/pest --group=feature
./vendor/bin/pest --group=unit

---

Git Commits

Phase 1 implementation tracked in 6 commits:

1. e1b0603 - Initial Laravel structure + models + controllers
2. 39b05f7 - Services, exceptions, middleware, tests
3. 94c98a8 - Configuration files and documentation
4. dfe223c - API documentation and expanded tests
5. 9279238 - Architecture documentation and finalization
6. e0b6195 - Phase 1 completion summary

---

Next Steps

This Week (Week 3)

• Build Docker containers: docker-compose up --build
• Run migrations: docker-compose exec laravel php artisan migrate
• Execute test suite: docker-compose exec laravel ./vendor/bin/pest
• Verify API endpoints
• Test external service integrations
• Generate test coverage report

Week 4 (Phase 1 Final)

• Performance testing
• Load testing with 1000+ articles
• Data migration from legacy PHP
• Final documentation updates
• Phase 1 verification & sign-off

Week 5-6 (Phase 2)

• Vue 3 + TypeScript project setup
• Pinia state management
• Vite dev server
• Tailwind CSS integration

---

Troubleshooting

Database Connection Error

# Check .env file
cat backend/.env

# Verify MySQL is running
docker-compose ps

# Check MySQL logs
docker-compose logs mysql

Tests Failing

# Run migrations in test environment
php artisan migrate --env=testing

# Run specific test
./vendor/bin/pest tests/Feature/ArticleControllerTest.php -v

# Clear cache
php artisan cache:clear

Docker Build Errors

# Rebuild containers
docker-compose down
docker-compose up --build

# Check Docker logs
docker-compose logs laravel

---

Support & Questions

For questions about:

• Backend Architecture: See backend/ARCHITECTURE.md
• API Usage: See API_DOCUMENTATION.md
• Setup & Development: See BACKEND_README.md
• Overall Plan: See MODERNIZATION.md
• Current Status: See PROGRESS.md

---

Timeline

Week 1-2: ✅ Backend Setup & API Endpoints (COMPLETE)
Week 3-4: ⏳ Services & Testing & Docker (IN PROGRESS)
Week 5-6: ⏳ Frontend Framework Setup
Week 7-9: ⏳ UI Components & Features
Week 9-10: ⏳ Testing & Optimization
Week 10-11: ⏳ Deployment & Documentation

---

Technology Stack

Backend

• Framework: Laravel 11
• Language: PHP 8.2
• Database: MySQL 8.0
• Testing: Pest
• Server: Nginx + PHP-FPM
• Container: Docker Compose

Frontend (Phase 2)

• Framework: Vue 3
• Language: TypeScript
• Build Tool: Vite
• State: Pinia
• Styling: Tailwind CSS
• Testing: Vitest + Cypress

---

License

Internal project for Article Review System modernization.

---

Project Metadata

• Repository: article-review
• Version: 1.0 (Phase 1)
• PHP Version: 8.2+
• Laravel Version: 11
• Node Version: 18+ (for frontend)
• Start Date: 2026-06-22
• PM: Claude Code
• Team: 1 Developer + PM

---

Last Updated: 2026-06-22
Status: Phase 1 - 85% Complete
Next Review: End of Week 3