GNX-WEB/gnx-react/backend/case_studies/README.md

# Case Studies API

## Overview

The Case Studies API provides a comprehensive backend and frontend solution for managing and displaying case study content. This feature includes categories, clients, process steps, gallery images, and related case studies.

## Backend Structure

### Models

1. **CaseStudyCategory**
   - Category management for case studies
   - Fields: name, slug, description, display_order, is_active

2. **Client**
   - Client information management
   - Fields: name, slug, logo, description, website

3. **CaseStudy**
   - Main case study model
   - Fields: title, slug, subtitle, description, excerpt
   - Images: thumbnail, featured_image, poster_image, project_image
   - Relations: category, client
   - Content: project_overview, site_map_content

4. **CaseStudyImage**
   - Gallery images for case studies
   - Fields: image, caption, display_order

5. **CaseStudyProcess**
   - Process steps for case studies
   - Fields: step_number, title, description

### API Endpoints

Base URL: `/api/case-studies/`

#### Case Studies

- `GET /case-studies/` - List all case studies (with pagination and filtering)
  - Query params: `category`, `client`, `search`, `featured`, `ordering`, `page`, `page_size`
- `GET /case-studies/{slug}/` - Get case study details
- `GET /case-studies/featured/` - Get featured case studies
- `GET /case-studies/latest/?limit=6` - Get latest case studies
- `GET /case-studies/popular/?limit=6` - Get popular case studies
- `GET /case-studies/{slug}/related/` - Get related case studies

#### Categories

- `GET /categories/` - List all categories
- `GET /categories/{slug}/` - Get category details
- `GET /categories/with_case_studies/` - Get categories with case studies

#### Clients

- `GET /clients/` - List all clients
- `GET /clients/{slug}/` - Get client details
- `GET /clients/{slug}/case_studies/` - Get case studies for a client

## Frontend Structure

### API Service (`lib/api/caseStudyService.ts`)

Provides TypeScript functions for all API endpoints with proper typing.

### Hooks (`lib/hooks/useCaseStudy.ts`)

React hooks for data fetching:
- `useCaseStudies()` - Fetch all case studies
- `useCaseStudy(slug)` - Fetch single case study
- `useFeaturedCaseStudies()` - Fetch featured case studies
- `useLatestCaseStudies()` - Fetch latest case studies
- `usePopularCaseStudies()` - Fetch popular case studies
- `useRelatedCaseStudies(slug)` - Fetch related case studies
- `useCaseStudyCategories()` - Fetch categories
- `useClients()` - Fetch clients

### Components

1. **CaseItems** (`components/pages/case-study/CaseItems.tsx`)
   - Lists all case studies in a grid
   - Includes tab navigation for "Case Study" and "Client" views
   - Dynamically rendered from API data

2. **CaseSingle** (`components/pages/case-study/CaseSingle.tsx`)
   - Displays detailed case study information
   - Shows poster image, project overview, and gallery
   - Dynamically rendered from API data

3. **Process** (`components/pages/case-study/Process.tsx`)
   - Displays process steps for a case study
   - Dynamically rendered from API data

4. **RelatedCase** (`components/pages/case-study/RelatedCase.tsx`)
   - Shows related case studies
   - Dynamically rendered from API data

### Pages

- `/case-study` - Lists all case studies
- `/case-study/[slug]` - Displays individual case study

## Setup Instructions

### Backend Setup

1. Add `'case_studies'` to `INSTALLED_APPS` in `settings.py` ✅
2. Run migrations:
   ```bash
   python manage.py makemigrations case_studies
   python manage.py migrate case_studies
   ```

3. Populate sample data:
   ```bash
   python manage.py populate_case_studies
   ```

4. Add URL patterns to main `urls.py`:
   ```python
   path('api/case-studies/', include('case_studies.urls')),
   ```

### Frontend Setup

The frontend is already integrated and ready to use. The components will automatically fetch data from the API when the pages load.

## Admin Panel

Access the Django admin panel to manage:
- Case Study Categories
- Clients
- Case Studies
- Case Study Images
- Case Study Process Steps

URL: `/admin/`

## Data Population

The `populate_case_studies` management command creates:
- 6 case study categories
- 4 clients
- 8 case studies
- 32 gallery images
- 40 process steps

## Features

✅ Full CRUD operations via Django admin
✅ RESTful API with filtering and pagination
✅ Dynamic frontend with React hooks
✅ Image support (local and external URLs)
✅ Related case studies
✅ Process steps with ordering
✅ Gallery images with captions
✅ Category and client management
✅ Featured and popular case studies
✅ SEO fields (meta description, keywords)
✅ View count tracking

## Testing the API

You can test the API using:

1. Django REST Framework browsable API:
   - Navigate to `http://localhost:8000/api/case-studies/case-studies/`

2. Swagger UI:
   - Navigate to `http://localhost:8000/swagger/`

3. Frontend:
   - Navigate to `http://localhost:3000/case-study`

## Example API Response

```json
{
  "id": 1,
  "title": "Artificial intelligence is the simulation of human processes",
  "slug": "artificial-intelligence-is-the-simulation-of-human-processes",
  "subtitle": "AI-Powered Business Solutions",
  "excerpt": "This artificial intelligence project demonstrates...",
  "thumbnail": "/images/case/one.png",
  "category": {
    "id": 4,
    "name": "AI",
    "slug": "ai"
  },
  "client": {
    "id": 1,
    "name": "Tarapio",
    "slug": "tarapio"
  },
  "gallery_images": [...],
  "process_steps": [...],
  "related_case_studies": [...]
}
```

## Notes

- All images support both uploaded files and external URLs
- Slugs are automatically generated from titles
- Case studies are ordered by display_order and published_at
- Only published case studies are returned via the API
- View counts are automatically incremented when viewing details