## JUNO

![JUNO logo](./public/icon.png)

**Tech stack:** ⚛️ Next.js · 💙 TypeScript · 🐘 PostgreSQL · ☁️ AWS Bedrock · 📬 Gmail API · 🐳 Docker · 🔐 NextAuth

Modern commerce and support infrastructure for Shopify‑based dropshipping businesses. 🚀

JUNO is a full‑stack Next.js application that powers:

- A **Vendor Portal** for Shopify merchants
- A **Supplier Portal** for product providers
- An **Admin view** for operations
- An AI‑powered helpdesk and knowledge engine called **JUNOCHAT / Juno Engine**

Everything runs inside a single Next.js App Router project (frontend + backend + background jobs).

---

## Table of Contents

1. [High‑Level Overview](#high-level-overview)
2. [Core Features](#core-features)
   - [Vendor Portal](#vendor-portal)
   - [Supplier Portal](#supplier-portal)
   - [Admin / Ops](#admin--ops)
   - [JUNOCHAT (AI Helpdesk)](#junochat-ai-helpdesk)
3. [Architecture & Tech Stack](#architecture--tech-stack)
4. [Problems & Solutions](#problems--solutions)
5. [Future Enhancements](#future-enhancements)
   - [JUNOCHAT & AI](#future-enhancements-for-junochat--ai)
6. [Local Development](#local-development)
7. [Docker & Deployment](#docker--deployment)
8. [AWS Bedrock & AI Setup](#aws-bedrock--ai-setup)
9. [Prisma & Database](#prisma--database)
10. [License](#license)

---

## High‑Level Overview

JUNO centralizes communication and operations between **vendors** (Shopify stores) and **suppliers**:

- Vendors can:
  - Connect Shopify stores and sync products.
  - Receive products and price offers from suppliers.
  - See new products in a clean, auto‑refreshing **New Products** view.
  - Get notifications when suppliers change prices or withdraw products.

- Suppliers can:
  - Manage their product catalog with images and pricing.
  - Accept product sync requests from vendors.
  - Provide products and custom pricing per vendor.
  - Edit synced product price/quantity **per vendor** with inline controls.

- Both sides are supported by:
  - **JUNOCHAT** – an AI assistant powered by AWS Bedrock (Titan + Claude) that can answer questions based on the knowledge base and FAQs.
  - A **Juno Engine** area for Gmail and ticketing workflows.

---

## Core Features

### Vendor Portal

- **Shopify connections**
  - Connect one or more Shopify stores to JUNO.
  - Webhooks keep orders, inventory, and products in sync.

- **New Products**
  - Consolidated list of:
    - Products vendors requested and had **synced** by suppliers.
    - Products **provided directly** by suppliers via offers.
  - Clean row‑based layout (no heavy cards) that:
    - Auto‑refreshes in the background on an interval and when the tab becomes visible.
    - Avoids UI flicker by only updating when data actually changes.
  - Product detail sheet with:
    - Price
    - Supplier
    - Optional quantity/amount
    - Description and image
  - Clicking outside the detail closes it (no need to aim at a tiny “X”).

- **Suppliers Directory**
  - Discover global suppliers.
  - Send connection invitations.
  - Track connection status (PENDING / CONNECTED / REJECTED).

- **Notifications**
  - Vendors are notified when:
    - A supplier accepts a product sync request.
    - A supplier provides a new product.
    - A supplier updates the price or quantity of an offered/synced product.

### Supplier Portal

- **Vendor Connections**
  - Accept invitations using secure tokens.
  - See all connected vendors with status filters.
  - Accept / reject product sync requests from vendors with a dedicated panel.

- **Synced Products Per Vendor**
  - For each vendor, suppliers see a **synced products** block:
    - Compact, scrollable list for large catalogs.
    - Shows image, title, SKU, description.
    - Inline edit controls for:
      - **Price** (for that vendor)
      - **Available amount / quantity** (for that vendor)
  - Updates flow through `ProductSync` so the vendor’s New Products view reflects the new price/amount.

- **Provided Products (Offers)**
  - Suppliers can:
    - Select products from their catalog.
    - Specify **per‑vendor price** and **total quantity**.
    - See all offers in a tidy list with image, SKU, and timestamps.
  - **Edit offer**:
    - Opens a modal (no page jump) to change price and quantity.
    - Sends a notification to the vendor about the update.
  - **Withdraw offer**:
    - Opens a custom confirmation dialog:
      - “You are about to withdraw *{productName}* from *{vendorName}*…”
    - On confirm, removes the offer and the product disappears from the vendor’s New Products list.

- **Products Catalog**
  - Manage own products (create/update/delete).
  - Upload images via:
    - S3 in hosted environments, or
    - Local `public/uploads` in pure local dev.
  - Safeguards:
    - Synced products from vendors are **editable but not deletable**.
    - UI labels clarify when a product is “Synced” and where it came from.

### Admin / Ops

- Admin page with an overview of:
  - Stores
  - Vendors
  - Suppliers
  - Juno Engine activity

- Email‑centric ops:
  - Gmail polling and webhook endpoints.
  - Email logs and templates.
  - MFA setup, notifications, and account hygiene flows.

### JUNOCHAT (AI Helpdesk)

JUNOCHAT (a.k.a. Juno Engine chat) is the AI layer that:

- Uses **AWS Bedrock**:
  - **Amazon Titan Text Embeddings V2** for vector embeddings.
  - **Anthropic Claude 3 Haiku** for chat and knowledge‑base answers.
- Supports:
  - FAQ ingestion and retrieval.
  - Knowledge document upload + chunking.
  - RAG‑style responses for store‑specific questions (orders, products, policies, etc.).
- Integrates with the rest of JUNO:
  - Can respond based on vendor/supplier context.
  - Ties into the Juno Engine Gmail / ticketing workflow so AI can assist with replies.

---

## Future Enhancements

### Future Enhancements for JUNOCHAT & AI

- **Deeper Shopify awareness**
  - Let JUNOCHAT answer questions like:
    - “Which supplier provides the top‑selling items in the last 30 days?”
    - “What is the margin per vendor on synced products?”

- **Multi‑channel support**
  - Extend Juno Engine beyond Gmail:
    - WhatsApp / SMS
    - Messenger / Instagram DMs
    - Shopify Inbox

- **Active suggestion engine**
  - Use embeddings + usage data to:
    - Suggest products suppliers should offer to specific vendors.
    - Recommend pricing bands per market/region.

- **Self‑service playbooks**
  - Let admins define reusable “AI playbooks”, e.g.:
    - “Handle delayed shipment” flow.
    - “Out‑of‑stock product” flow.
  - JUNOCHAT would follow these playbooks when generating replies.

---

## Architecture & Tech Stack

- **Framework**: Next.js (App Router, TypeScript)
- **UI**: React + Tailwind‑style utility classes
- **Auth**: NextAuth
- **Database**: PostgreSQL via Prisma ORM
- **Background / Integrations**:
  - Gmail APIs (OAuth)
  - Shopify APIs (orders, products, inventory)
  - AWS Bedrock (Titan embeddings + Claude 3 Haiku chat)
- **Deployment**: Docker + GitHub Actions → AWS EC2

---

## Problems & Solutions

### 1. Dropshipping is glued together with spreadsheets and chats 😵‍💫

**Typical Shopify dropshipping today:**

- Vendors discover suppliers in WhatsApp groups, email threads, or random marketplaces.
- Product info, pricing, and availability live in:
  - Google Sheets
  - Excel files
  - Long chat histories and voice notes
- When something changes (price increases, product discontinued), it’s easy to miss and very hard to trace.

**How JUNO helps:**

- Formal **connections** between Shopify stores and suppliers.
- Structured models (`ProductSync`, `SupplierProductOffer`) instead of ad‑hoc spreadsheets.
- Every new product or change becomes:
  - A record in the database.
  - A visible entry in the **New Products** list.
  - A notification to the affected party (vendor or supplier).

👉 Result: less “Did you see my message?” and more “The system already updated this.”  

### 2. No single source of truth for cost, price, and margin per vendor 💸

**In a typical Shopify setup:**

- Supplier sends a Google Sheet with “latest prices”.
- Vendor copies that into Shopify, maybe with manual mark‑ups.
- If the supplier changes cost for **one** vendor, everyone else may still see old prices.
- Nobody is sure what the **current agreed cost** is for a given product/vendor pair.

**How JUNO helps:**

- Suppliers manage **per‑vendor offers** directly in the Supplier Portal:
  - Price and quantity are editable inline.
  - Synced products from vendors can be overridden per store.
- Vendors see the resulting price and available amount in one place:
  - The **New Products** page, refreshed in the background.
  - Notifications whenever suppliers change price/quantity.

👉 Result: vendors always see the latest cost per product per supplier, and suppliers stay in control of what each partner gets.  

### 3. Operational noise across email, tickets, and knowledge 💬

**Pain today:**

- Support lives in Gmail, while operations live in Shopify, and documentation is buried in Notion/Docs.
- Agents manually copy/paste order IDs, tracking links, and policy snippets into replies.
- Repeated questions (“Where is my order?”, “What’s your return policy?”) steal time from real issues.

**How JUNO helps:**

- **JUNOCHAT + Juno Engine**:
  - Ingest FAQs and internal docs into a vectorized knowledge base (via Bedrock embeddings).
  - Answer questions using **RAG** against that knowledge.
  - Integrate with Gmail so tickets and AI context live in the same place.

👉 Result: fewer repetitive replies, faster accurate responses, and a single surface for “what we know” + “what customers ask”.  

---

## Local Development

1. **Install dependencies**

```bash
npm install
```

2. **Create `.env`**

Copy `.env.example` (or the variables listed below) into a local `.env` file and fill in your own values:

- `DATABASE_URL`
- `NEXTAUTH_SECRET`
- `NEXTAUTH_URL`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `SMTP_HOST`
- `SMTP_PORT`
- `SMTP_SECURE`
- `SMTP_USER`
- `SMTP_PASSWORD`
- `AWS_ACCESS_KEY_ID` (for AWS Bedrock)
- `AWS_SECRET_ACCESS_KEY` (for AWS Bedrock)
- `AWS_REGION` (default: `us-east-1`)
- `ADMIN_EMAIL`
- `ADMIN_PASSWORD`

> Never commit real secrets; `.env*` files are ignored by git.

3. **Run the dev server**

```bash
npm run dev
```

Visit `http://localhost:3000` in your browser.

---

## Docker & Deployment

The project can be run via Docker using the provided `Dockerfile` and `docker-compose.yml`.

Typical pattern:

```bash
docker compose up -d --build
```

Make sure your `.env` is present next to the app code so the container can read it.

### CI/CD on AWS EC2

This repo includes a GitHub Actions workflow at `.github/workflows/deploy-ec2.yml` that:

1. Runs on pushes to the `main` branch.
2. Installs dependencies and builds the Next.js app.
3. SSHes into an EC2 instance.
4. Writes an `.env` file on the EC2 instance from a **single GitHub secret** `EC2_ENV`.
5. Uses `docker compose` / `docker-compose` to build and run the app.
6. Performs a health check and **automatically rolls back** to the previous commit if the deployment or health check fails.

#### Required GitHub Secrets

Set the following secrets in **GitHub → Settings → Secrets and variables → Actions**:

- `EC2_HOST` – public IP or DNS of the EC2 instance.
- `EC2_USER` – SSH user (e.g. `ubuntu`).
- `EC2_SSH_KEY` – private SSH key for that user.
- `EC2_SSH_PORT` – (optional) port, defaults to `22` if not set.
- `EC2_ENV` – **multi-line secret containing the full contents of the `.env` file** used in production.  
  This is written to `.env` on the server during deployment.

#### Deployment Flow

- Push to `main`.
- GitHub Actions:
  - Builds the app.
  - Connects to EC2.
  - Writes `.env` from `EC2_ENV`.
  - Runs `docker compose up -d --build`.
  - Hits the health check URL (by default `http://localhost:3000/api/health`).
- If the health check fails, the workflow:
  - Resets the repo on EC2 to the previous commit.
  - Re-runs `docker compose up -d --build`.

This gives you a sharp deployment with an automatic rollback path.

---

## AWS Bedrock & AI Setup

The knowledge base and JUNOCHAT features use AWS Bedrock for AI‑powered embeddings and chat completion.

### Prerequisites

1. **AWS Account**: Create an account at `https://aws.amazon.com/`
2. **Enable Bedrock Access**: 
   - Go to `https://console.aws.amazon.com/bedrock/`
   - Navigate to **Model access**
   - Request access to:
     - **Amazon Titan Text Embeddings V2** (for embeddings)
     - **Anthropic Claude 3 Haiku** (for chat completion)

### IAM Setup

Create an IAM user or role with Bedrock permissions:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel"],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0",
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
      ]
    }
  ]
}
```

Create access keys for that user and add them to `.env`:

```bash
AWS_ACCESS_KEY_ID="your-access-key-id"
AWS_SECRET_ACCESS_KEY="your-secret-access-key"
AWS_REGION="us-east-1"  # or your preferred region
```

### Database Migration & Re‑Embedding

After setting up AWS Bedrock:

1. Apply Prisma migrations:

```bash
npx prisma migrate deploy
```

2. Re‑embed existing knowledge base data:

```bash
npm run re-embed-knowledge-base
```

This script:

- Reads all existing `KnowledgeChunk` records.
- Generates new embeddings using Titan V2.
- Updates the database in batches to avoid rate limiting.

---

## Prisma & Database

To inspect the database locally:

```bash
export DATABASE_URL='<YOUR_DB_URL>'
npx prisma studio
```

---

## License

Private / All rights reserved unless explicitly stated otherwise.