docs: add comprehensive parapharmacy and N8N documentation

- Create docs/parapharmacy.md with full API, N8N, and setup documentation - Update README.md with parapharmacy system overview and links - Add project structure for parapharmacy-api and n8n - Update Docker setup section with all services - Add API endpoints for parapharmacy - Add N8N workflow automation section
2026-07-16 12:51:48 +02:00
parent 52ddb9c21c
commit cb564fb170
2 changed files with 469 additions and 19 deletions
@@ -29,9 +29,11 @@ A web application to search for medicines from the official Spanish CIMA databas

 | App | Stack |
 |-----|-------|
-| Backend | Node.js + Express, SQLite, Redis |
+| Backend | Node.js + Express, SQLite/PostgreSQL, Redis |
+| Parapharmacy API | Node.js + Express, MongoDB |
 | Frontend (Web) | React + Vite, Capacitor |
 | Frontend (Mobile) | Expo SDK 57 + React Native, Zustand, Axios + TanStack Query |
+| Workflow Automation | N8N |
 | Build system | Turborepo |
 | Package manager | npm workspaces |

@@ -50,10 +52,11 @@ This is a **Turborepo monorepo**. All applications live under `apps/`:
 FarmaFinder/
 ├── package.json              # Root: workspaces + turbo scripts
 ├── turbo.json                # Turborepo task configuration
-├── docker-compose.yml        # Full stack: backend + frontend + Redis + Postgres
+├── docker-compose.yml        # Full stack: backend + frontend + Redis + Postgres + MongoDB + N8N
+├── .env.example              # Environment variables template
 │
 ├── apps/
-│   ├── backend/              # Node.js + Express API
+│   ├── backend/              # Node.js + Express API (medicines)
 │   │   ├── Dockerfile
 │   │   ├── server.js         # Express server and API routes
 │   │   ├── cima-service.js   # CIMA API integration with Redis cache
@@ -62,6 +65,18 @@ FarmaFinder/
 │   │   ├── create-admin.js   # Admin user creation script
 │   │   └── package.json
 │   │
+│   ├── parapharmacy-api/     # Parapharmacy products API
+│   │   ├── Dockerfile
+│   │   ├── src/
+│   │   │   ├── server.js     # Express + Swagger
+│   │   │   ├── config.js     # Configuration
+│   │   │   ├── models/
+│   │   │   │   └── Product.js
+│   │   │   └── routes/
+│   │   │       └── products.js
+│   │   ├── README.md
+│   │   └── package.json
+│   │
 │   ├── frontend/             # React + Vite (Desktop/PWA)
 │   │   ├── Dockerfile
 │   │   ├── nginx.conf        # Nginx config for Docker
@@ -79,7 +94,7 @@ FarmaFinder/
 │   │   ├── store/
 │   │   └── package.json
 │   │
-│   ├── scraper/              # Puppeteer scraper (standalone)
+│   ├── scraper/              # Puppeteer scraper (legacy)
 │   │   └── package.json
 │   │
 │   └── pip-platform/         # Python FastAPI platform (separate docker-compose)
@@ -87,11 +102,29 @@ FarmaFinder/
 │       ├── docker-compose.yml
 │       └── pyproject.toml
 │
+├── n8n/                      # N8N workflow automation
+│   ├── workflows/            # Workflow JSON files
+│   │   ├── parapharmacy-scraper.json
+│   │   └── parapharmacy-manual-scraper.json
+│   └── README.md
+│
 ├── API/                      # Shared API source files
 ├── scripts/                  # Build/utility scripts
 └── docs/                     # Documentation
+    └── parapharmacy.md       # Parapharmacy system documentation
 ```

+## Features
+
+### Parapharmacy Search
+- Scraping de múltiples tiendas españolas (Promofarma, Pharmarket, DocMorris, etc.)
+- API REST dedicada con MongoDB
+- Scraping automático cada 3 días via N8N
+- Búsqueda full-text por nombre, marca y categoría
+- [Documentación completa](docs/parapharmacy.md)
+
+---
+
 ## Quick Start

 ### Install dependencies
@@ -141,34 +174,53 @@ npm test --workspace=farma-clic-frontend

 ## Docker Setup

-Runs the full stack (backend, frontend, Redis, Postgres) with a single command.
+Runs the full stack with a single command.

 ```bash
-# Copy and configure environment (optional - defaults work for local dev)
-cp apps/backend/.env.example apps/backend/.env
+# Copy and configure environment
+cp .env.example .env
+# Edit .env with your settings (especially passwords)

 docker compose up --build
 ```

-App available at `http://localhost:4000` (frontend) and `http://localhost:3001` (backend API).
+### Services
+
+| Service | URL | Description |
+|---------|-----|-------------|
+| Frontend | http://localhost:4000 | React web app |
+| Backend API | http://localhost:3001 | Medicines API |
+| Parapharmacy API | http://localhost:3002 | Parapharmacy products API |
+| Swagger Docs | http://localhost:3002/api/docs | API documentation |
+| N8N | http://localhost:5678 | Workflow automation |
+
+### First Run

-**First run - create an admin user:**
 ```bash
+# Create admin user for FarmaFinder
 docker compose exec backend node create-admin.js
-# Default: admin / admin123 - change after first login
-```
+# Default: admin / admin123

-**Seed sample pharmacies:**
-```bash
+# Seed sample pharmacies
 docker compose exec backend node seed.js
 ```

-**Stop:**
+### N8N Setup
+
+N8N auto-creates an admin account on first start:
+- **Email**: admin@farmafinder.com
+- **Password**: change-me (configurable in `.env`)
+
+See [Parapharmacy Documentation](docs/parapharmacy.md) for details.
+
+### Stop
+
 ```bash
 docker compose down
 ```

-Database is persisted in named Docker volumes (`backend_data`, `postgres_data`). To wipe:
+### Reset Data
+
 ```bash
 docker compose down -v
 ```
@@ -225,18 +277,26 @@ npm run dev

 ## API Endpoints

-### Public
- `GET /api/medicines/search?q=<query>` - Search medicines (CIMA API, cached in Redis)
+### Medicines (Backend - Port 3001)
+
+**Public:**
+- `GET /api/medicines/search?q=<query>` - Search medicines (CIMA API)
 - `GET /api/medicines/:nregistro` - Medicine details
 - `GET /api/medicines/:nregistro/pharmacies` - Pharmacies selling a medicine
 - `GET /api/pharmacies` - All pharmacies

-### Auth
+**Parapharmacy Proxy:**
+- `GET /api/products/parapharmacy/search?q=<query>` - Search parapharmacy products
+- `GET /api/products/parapharmacy/:id` - Parapharmacy product details
+- `GET /api/products/parapharmacy/categories` - List categories
+- `GET /api/products/parapharmacy/brands` - List brands
+
+**Auth:**
 - `POST /api/auth/login` - Login
 - `POST /api/auth/logout` - Logout
 - `GET /api/auth/check` - Check auth status

-### Admin (requires authentication)
+**Admin:**
 - `POST /api/admin/pharmacies` - Add pharmacy
 - `PUT /api/admin/pharmacies/:id` - Update pharmacy
 - `DELETE /api/admin/pharmacies/:id` - Delete pharmacy
@@ -246,6 +306,23 @@ npm run dev
 - `PUT /api/admin/pharmacy-medicines/:id` - Update price/stock
 - `DELETE /api/admin/pharmacy-medicines/:id` - Remove link

+### Parapharmacy API (Port 3002)
+
+- `GET /api/products/search?q=<query>` - Search products (full-text)
+- `GET /api/products/:id` - Product details
+- `GET /api/products` - List products
+- `POST /api/products` - Create product
+- `POST /api/products/bulk` - Bulk upsert (for scrapers)
+- `PUT /api/products/:id` - Update product
+- `DELETE /api/products/:id` - Delete product
+- `GET /api/products/categories` - List categories
+- `GET /api/products/brands` - List brands
+- `GET /api/sources` - Configured sources
+- `GET /api/health` - Health check
+- `GET /api/docs` - Swagger documentation
+
+See [Parapharmacy Documentation](docs/parapharmacy.md) for details.
+
 ## Database Schema

 ### SQLite Tables
@@ -320,6 +397,32 @@ const ENV = {
 };
 ```

+## N8N Workflow Automation
+
+N8N handles automated scraping of parapharmacy products.
+
+### Access
+- **URL**: http://localhost:5678
+- **Email**: admin@farmafinder.com
+- **Password**: change-me (change in `.env`)
+
+### Workflows
+
+| Workflow | Trigger | Description |
+|----------|---------|-------------|
+| Parapharmacy Scraper | Every 3 days at 2am | Automatic scraping (inactive by default) |
+| Parapharmacy Manual Scraper | POST `/webhook/scrape-parapharmacy` | On-demand scraping |
+
+### Manual Scraping
+
+```bash
+curl -X POST http://localhost:5678/webhook/scrape-parapharmacy
+```
+
+See [N8N Documentation](n8n/README.md) for details.
+
+---
+
 ## Troubleshooting

 ### Redis Connection Issues