451 lines
14 KiB
Markdown
451 lines
14 KiB
Markdown
## JUNO
|
||
|
||
<p align="center">
|
||
<img src="./public/icon.png" alt="JUNO logo" width="420" />
|
||
</p>
|
||
|
||
**Tech stack**
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
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.
|