basil/README.md

Basil 🌿

A modern, full-stack recipe manager with web and mobile support. Import recipes from any URL, manage your recipe collection, and access them from anywhere.

Features

• Recipe Import: Automatically import recipes from URLs using schema.org markup
• Full Recipe Management: Create, read, update, and delete recipes
• Rich Recipe Data: Store ingredients, instructions, prep/cook times, servings, images, and more
• Search & Filter: Find recipes by title, cuisine, category, or tags
• Multiple Images: Add multiple images to each recipe
• Flexible Storage: Local filesystem storage by default, optional S3 support
• Docker Support: Easy deployment with Docker Compose
• API-First Design: RESTful API for web and future mobile apps

Tech Stack

• Backend: Node.js, TypeScript, Express, Prisma ORM, PostgreSQL
• Frontend: React, TypeScript, Vite, React Router
• Infrastructure: Docker, Docker Compose, nginx
• Monorepo: npm workspaces with shared types

Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 16+ (or use Docker)
• Docker (optional, for containerized deployment)

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd basil
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   cp packages/api/.env.example packages/api/.env
   # Edit packages/api/.env with your database credentials
   

4. Start PostgreSQL (if not using Docker)

   # Create a database named 'basil'
   createdb basil
   

5. Run database migrations

   cd packages/api
   npm run prisma:migrate
   npm run prisma:generate
   cd ../..
   

6. Start development servers

   npm run dev
   

   This starts:

   • API server at http://localhost:3001
   • Web frontend at http://localhost:5173

Docker Deployment

For production or easy local setup:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Services will be available at:

• Web: http://localhost:5173
• API: http://localhost:3001
• PostgreSQL: localhost:5432

Project Structure

basil/
├── packages/
│   ├── api/          # Backend API server
│   │   ├── prisma/   # Database schema and migrations
│   │   └── src/      # Express routes, services, config
│   ├── web/          # React web application
│   │   └── src/      # Components, pages, services
│   └── shared/       # Shared TypeScript types
├── docker-compose.yml
└── package.json      # Workspace root

Usage

Importing a Recipe

1. Navigate to "Import Recipe" in the web app
2. Paste a recipe URL (from sites like AllRecipes, Food Network, etc.)
3. Preview the imported recipe
4. Save to your collection

API Examples

Import recipe from URL:

curl -X POST http://localhost:3001/api/recipes/import \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/recipe"}'

Get all recipes:

curl http://localhost:3001/api/recipes

Create a recipe:

curl -X POST http://localhost:3001/api/recipes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chocolate Chip Cookies",
    "ingredients": [
      {"name": "flour", "amount": "2", "unit": "cups", "order": 0}
    ],
    "instructions": [
      {"step": 1, "text": "Preheat oven to 350°F"}
    ]
  }'

Configuration

Storage Options

Local Storage (Default):

STORAGE_TYPE=local
LOCAL_STORAGE_PATH=./uploads

S3 Storage:

STORAGE_TYPE=s3
S3_BUCKET=your-bucket-name
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key

Database

Default PostgreSQL connection:

DATABASE_URL=postgresql://basil:basil@localhost:5432/basil?schema=public

For external database services (AWS RDS, DigitalOcean, etc.), update the connection string.

Development

Commands

# Install dependencies
npm install

# Start all services in development mode
npm run dev

# Build all packages
npm run build

# Lint all packages
npm run lint

# Docker commands
npm run docker:up
npm run docker:down
npm run docker:build

Database Migrations

cd packages/api

# Create a new migration
npm run prisma:migrate

# Generate Prisma client
npm run prisma:generate

# Open Prisma Studio (GUI for database)
npm run prisma:studio

Future Enhancements

• Mobile apps (React Native for iOS and Android)
• User authentication and multi-user support
• Recipe sharing and social features
• Meal planning and grocery lists
• Nutritional information calculation
• Recipe scaling (adjust servings)
• Print-friendly recipe view
• Recipe collections and cookbooks

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.