Skip to content

CLAUDE.md

Latest commit

 

History

History
77 lines (62 loc) · 3.05 KB

CLAUDE.md

File metadata and controls

77 lines (62 loc) · 3.05 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A full-stack news aggregation platform with personalized feeds and 3D globe visualization. The project uses Docker to orchestrate four services: a React frontend, Laravel API backend, Flask NLP microservice, and MySQL database.

Development Commands

Start Development Environment

docker-compose up --build

Service Ports

Laravel Commands (run inside container)

docker-compose exec laravel-app php artisan migrate     # Run migrations
docker-compose exec laravel-app php artisan test        # Run PHPUnit tests
docker-compose exec laravel-app php artisan articles:fetch  # Manually fetch articles
docker-compose exec laravel-app php artisan pint        # Run Laravel Pint linter

React Commands (run inside container or in my-app/)

cd my-app && npm start    # Development server
cd my-app && npm test     # Run Jest tests
cd my-app && npm run build  # Production build

Architecture

Multi-Container Docker Setup

  • laravel-app: PHP 8.2 + Apache serving the REST API
  • react-app: React 18 frontend (my-app directory)
  • flask-app: Python NLP service for location extraction
  • db: MySQL 5.7 database

Laravel Backend (laravel-app/)

  • Services Layer (app/Services/): API integrations for news sources
    • NewsAPIService - NewsAPI.org integration
    • GuardianService - The Guardian API
    • TimesService - NY Times API (BBC)
    • ArticleLocationService - Communicates with Flask service
  • Scheduled Command: articles:fetch fetches news from all sources and updates location data
  • Models: User, Article, Category, Source, Preference
  • Authentication: Laravel Sanctum with custom api.auth middleware
  • Vendor directory stored at /srv/vendor for Docker performance optimization

React Frontend (my-app/)

  • Pages: HomePage (with 3D globe), NewsFeed, UserProfile, Login/Signup
  • Components: Header, Footer, ArticleCard, FilterComponent, Globe
  • 3D Visualization: Three.js + @react-three/fiber for interactive Earth map
  • Styling: Tailwind CSS

Flask NLP Service (flask-app/)

  • Single endpoint: POST /extract-locations-batch
  • Uses spaCy for named entity recognition (GPE - geopolitical entities)
  • Uses geopy/Nominatim for geocoding locations to coordinates

Data Flow

  1. Cron job triggers articles:fetch command
  2. Laravel fetches from NewsAPI, Guardian, and Times APIs
  3. Articles saved to MySQL, then sent to Flask for location extraction
  4. Flask uses NLP to identify locations and geocode them
  5. Coordinates stored with articles for 3D globe visualization

Key API Routes (laravel-app/routes/api.php)

  • Public: /articles, /search-articles, /filter-articles, /location-articles
  • Auth-protected: /user, /preferences, /personalized-articles
  • Admin: /fetch-articles, /get-locations