# 🔌 Integration Guide: Recipe Import Service

Denna guide visar hur du integrerar **recipe-document-converter** (import-service) med din befintliga **recipe-app**.

## 📋 Innehållsförteckning

1. [Installation & Setup](#installation--setup)
2. [Arkitektur](#arkitektur)
3. [Backend Integration](#backend-integration)
4. [Docker Deployment](#docker-deployment)
5. [API Endpoints](#api-endpoints)
6. [Testing](#testing)
7. [Troubleshooting](#troubleshooting)

---

## Installation & Setup

### 1. Krav

- **recipe-app** — Din befintliga receptapp (Next.js frontend + NestJS backend)
- **recipe-document-converter** — Import-service (denna repo)
- **Docker** 24+ och **Docker Compose**
- **Node.js** 22.x

### 2. Klona och organisera projekten

```bash
dev/
├── recipe-app/                    # Din befintliga app
│   ├── frontend/
│   ├── backend/
│   ├── Dockerfile
│   └── compose.yml
│
└── recipe-document-converter/     # Import-service
    ├── recipe-document-converter/
    ├── Dockerfile
    ├── docker-compose.yml
    ├── Caddyfile
    └── README.md
```

### 3. Uppdatera recipe-document-converter paket

```bash
cd recipe-document-converter/recipe-document-converter

# TypeScript är redan uppdaterad till 5.4.5 ✅
# Installera dependencies
npm install
```

---

## Arkitektur

### System Diagram

```
┌─────────────────────────────────────────────────────────┐
│                    Caddy Reverse Proxy                  │
│                    (port 80/443)                        │
└────────────┬────────────────┬─────────────────┬─────────┘
             │                │                 │
     ┌───────▼───┐    ┌──────▼────────┐    ┌──▼─────────┐
     │ Frontend  │    │  Backend API  │    │   Import   │
     │ :4000     │    │  :3001        │    │   :3000    │
     │           │    │  (NestJS)     │    │ (NestJS)   │
     │ Next.js   │    │               │    │            │
     │ 16.2      │    │ Recipes ┐     │    │ PDF        │
     │           │    │ Inventory   ├─────┼──extract    │
     └───────────┘    │ Products │   │    │ structure  │
                      │           │   │    │            │
                      └──────┬────┘   │    └──────┬──────┘
                             │       │           │
                      ┌──────▼──────────────┐    │
                      │   MariaDB 11        │    │
                      │   (recipe_db)       │    │
                      └─────────────────────┘    │
                                                  │
                                    ┌─────────────▼─┐
                                    │ Uploads/      │
                                    │ (Volym)       │
                                    └───────────────┘
```

### Data Flow

```
1. Användare laddar upp PDF
   ↓
2. recipe-app frontend → backend POST /recipes/import/pdf
   ↓
3. Backend → FormData → import-service POST /import/pdf
   ↓
4. import-service extraherar → JSON (ingredients, instructions, metadata)
   ↓
5. Backend validerar + sparar i Prisma/MariaDB
   ↓
6. Frontend visar importerat recept
```

---

## Backend Integration

### Steg 1: Uppdatera recipe-app backend

```bash
cd recipe-app/backend

# Installera axios om det saknas
npm install axios

# Om du använder FormData
npm install form-data
```

### Steg 2: Skapa import-modul

Skapa `backend/src/modules/import/import.service.ts`:

```typescript
import { Injectable, HttpException, HttpStatus } from '@nestjs/common';
import axios from 'axios';
import FormData from 'form-data';
import * as fs from 'fs';
import { PrismaService } from '../../prisma/prisma.service';

interface RecipeImportDTO {
  name: string;
  ingredients: Array<{
    name: string;
    quantity?: number;
    unit?: string;
  }>;
  instructions: string[];
  metadata?: {
    prepTime?: string;
    servings?: number;
  };
}

@Injectable()
export class ImportService {
  private readonly IMPORT_SERVICE_URL = process.env.IMPORT_SERVICE_URL || 'http://import-service:3000';

  constructor(private prisma: PrismaService) {}

  async importRecipeFromPDF(file: Express.Multer.File) {
    try {
      if (!file) {
        throw new HttpException('Ingen fil angiven', HttpStatus.BAD_REQUEST);
      }

      if (file.mimetype !== 'application/pdf') {
        throw new HttpException('Endast PDF-filer tillåtna', HttpStatus.BAD_REQUEST);
      }

      // Call import-service
      const form = new FormData();
      form.append('file', fs.createReadStream(file.path));

      const response = await axios.post(`${this.IMPORT_SERVICE_URL}/import/pdf`, form, {
        headers: form.getHeaders(),
        timeout: 30000,
      });

      if (!response.data.success) {
        throw new HttpException(response.data.error, HttpStatus.BAD_REQUEST);
      }

      const recipeData = this.mapImportDataToRecipe(response.data.structuredData);

      return {
        success: true,
        data: recipeData,
        metadata: response.data.pdfMetadata,
      };
    } catch (error) {
      if (file?.path && fs.existsSync(file.path)) {
        fs.unlinkSync(file.path);
      }

      if (error instanceof axios.AxiosError) {
        throw new HttpException(
          `Import misslyckades: ${error.message}`,
          HttpStatus.SERVICE_UNAVAILABLE,
        );
      }

      throw error;
    }
  }

  async saveImportedRecipe(recipeData: RecipeImportDTO) {
    try {
      const recipe = await this.prisma.recipe.create({
        data: {
          name: recipeData.name,
          instructions: recipeData.instructions.join('\n'),
          prepTime: recipeData.metadata?.prepTime,
          servings: recipeData.metadata?.servings,
          ingredients: {
            create: recipeData.ingredients.map((ing) => ({
              name: ing.name,
              quantity: ing.quantity,
              unit: ing.unit,
            })),
          },
        },
        include: { ingredients: true },
      });

      return { success: true, message: 'Recept sparat', recipe };
    } catch (error) {
      throw new HttpException(
        `Kunde inte spara recept: ${error instanceof Error ? error.message : 'Okänt fel'}`,
        HttpStatus.INTERNAL_SERVER_ERROR,
      );
    }
  }

  private mapImportDataToRecipe(importedData: any): RecipeImportDTO {
    return {
      name: importedData.name || 'Importerat recept',
      ingredients: importedData.ingredients || [],
      instructions: importedData.instructions || [],
      metadata: importedData.metadata || {},
    };
  }
}
```

### Steg 3: Skapa import-modul

Skapa `backend/src/modules/import/import.module.ts`:

```typescript
import { Module } from '@nestjs/common';
import { ImportService } from './import.service';

@Module({
  providers: [ImportService],
  exports: [ImportService],
})
export class ImportModule {}
```

### Steg 4: Lägg till endpoints i recipes controller

Uppdatera `backend/src/modules/recipes/recipes.controller.ts`:

```typescript
import { Controller, Post, Get, UseInterceptors, UploadedFile } from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { ImportService } from '../import/import.service';

@Controller('recipes')
export class RecipesController {
  constructor(private importService: ImportService) {}

  /**
   * Import recipe from PDF without saving
   * POST /recipes/import/pdf
   */
  @Post('import/pdf')
  @UseInterceptors(FileInterceptor('file'))
  async importRecipeFromPDF(@UploadedFile() file: Express.Multer.File) {
    return this.importService.importRecipeFromPDF(file);
  }

  /**
   * Import and save recipe
   * POST /recipes/import/pdf/save
   */
  @Post('import/pdf/save')
  @UseInterceptors(FileInterceptor('file'))
  async importAndSaveRecipe(@UploadedFile() file: Express.Multer.File) {
    const imported = await this.importService.importRecipeFromPDF(file);
    return this.importService.saveImportedRecipe(imported.data);
  }

  /**
   * Check import service health
   * GET /recipes/import/health
   */
  @Get('import/health')
  async importServiceHealth() {
    return this.importService.checkImportServiceHealth();
  }
}
```

### Steg 5: Registrera import-modul

Uppdatera `backend/src/app.module.ts`:

```typescript
import { ImportModule } from './modules/import/import.module';

@Module({
  imports: [
    // ... existing modules
    ImportModule,
  ],
})
export class AppModule {}
```

---

## Docker Deployment

### Option 1: Lokal utveckling (utan Docker)

```bash
# Terminal 1: Start import-service
cd recipe-document-converter/recipe-document-converter
npm install
npm run start:dev

# Terminal 2: Start recipe-app backend
cd recipe-app/backend
npm install
IMPORT_SERVICE_URL=http://localhost:3000 npm run start:dev

# Terminal 3: Start recipe-app frontend
cd recipe-app/frontend
npm install
npm run dev
```

**Access:**
- Frontend: http://localhost:3000 (Next.js default)
- Backend: http://localhost:3001/api
- Import: http://localhost:3000/import

---

### Option 2: Docker Compose (Full Stack)

**Förutsättningar:**
- `recipe-app/` ligger bredvid `recipe-document-converter/`
- recipe-app har `Dockerfile` i root

**Starta all-in-one:**

```bash
cd recipe-document-converter/recipe-document-converter

# Bygg och starta alla tjänster
docker-compose up -d

# Eller med bygge
docker-compose up -d --build
```

**Tjänster:**
```
- Frontend: http://localhost (via Caddy)
- Backend API: http://localhost/api
- Import Service: http://localhost/import
- Health: http://localhost/health
```

**Se loggar:**
```bash
docker-compose logs -f recipe-app-backend
docker-compose logs -f import-service
docker-compose logs -f recipe-db
docker-compose logs -f caddy
```

**Stoppa allt:**
```bash
docker-compose down
```

---

## API Endpoints

### Import Service Endpoints

| Method | Endpoint | Beskrivning | Auth |
|--------|----------|-------------|------|
| `GET` | `/health` | Hälsokontroll | Nej |
| `POST` | `/import/pdf` | Importera PDF | Nej |

### Recipe App Backend Integration Endpoints

| Method | Endpoint | Beskrivning |
|--------|----------|-------------|
| `POST` | `/api/recipes/import/pdf` | Importera PDF (preview) |
| `POST` | `/api/recipes/import/pdf/save` | Importera och spara |
| `GET` | `/api/recipes/import/health` | Health check |

---

## Testing

### 1. Test import-service isolerat

```bash
curl -X POST \
  -F "file=@recipe.pdf" \
  http://localhost:3000/import/pdf
```

**Response:**
```json
{
  "success": true,
  "rawText": "...",
  "pdfMetadata": {
    "fileName": "recipe.pdf",
    "pages": 1,
    "author": "Unknown"
  },
  "structuredData": {
    "name": "Kycklingcurry",
    "ingredients": [...],
    "instructions": [...]
  }
}
```

### 2. Test recipe-app integration

```bash
curl -X POST \
  -F "file=@recipe.pdf" \
  http://localhost:3001/api/recipes/import/pdf
```

### 3. Test health checks

```bash
# Import service
curl http://localhost:3000/health

# Recipe app backend
curl http://localhost:3001/health

# Import from backend
curl http://localhost:3001/api/recipes/import/health
```

### 4. Test full end-to-end (Docker)

```bash
# Start services
docker-compose up -d

# Wait for services to be healthy
sleep 10

# Check all services
curl http://localhost/health
curl http://localhost/api/health
curl http://localhost/import/health

# Import recipe
curl -X POST \
  -F "file=@recipe.pdf" \
  http://localhost/api/recipes/import/pdf/save
```

---

## Troubleshooting

### Import Service är inte tillgänglig

```bash
# Kontrollera om den körs
docker ps | grep import-service

# Se loggar
docker logs recipe-import-service

# Kontrollera hälsa
curl http://localhost:3000/health
```

### Docker nätverk-error

```bash
# Reinitialize docker-compose
docker-compose down
docker system prune -a
docker-compose up --build
```

### Filuppladdning misslyckas

```bash
# Kontrollera filstorlek (default 50MB)
ls -lh recipe.pdf

# Kontrollera uploads-mapp permissions
docker exec recipe-import-service ls -la /app/uploads/
```

### TypeScript fel

```bash
# Uppdatera dependencies
npm install

# Clear cache
npm cache clean --force

# Rebuild
npm run build
```

### Databas-anslutning misslyckad

```bash
# Kontrollera MariaDB
docker logs recipe-db

# Kontrollera URL
echo $DATABASE_URL

# Test direkten
docker exec recipe-db mysql -urecipe_user -psecure_password -e "USE recipe_db; SHOW TABLES;"
```

---

## Production Checklist

- [ ] TypeScript compilerar utan fel
- [ ] Alla miljövariabler är satta
- [ ] Database-backup är konfigurerat
- [ ] Import-service är tillgänglig från backend
- [ ] Caddy certifikater är satta upp
- [ ] Log rotation är konfigurerat
- [ ] Health endpoints fungerar
- [ ] File uploads permissions är rätt
- [ ] Rate limiting är konfigurerat (if needed)
- [ ] Monitoring setup är på plats

---

## Nästa steg

1. **LLM Integration** — Lägg till Mistral för avancerad strukturering
2. **Excel/Word support** — Expandera till fler filformat
3. **OCR** — Lägg till stöd för skannade dokument
4. **Caching** — Implementera Redis för snabbare import
5. **Authentication** — Lägg till auth om behövs

---