Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VisualGraphxLLC/API-HUB/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through spinning up a complete local API-HUB environment: PostgreSQL and n8n in Docker, the FastAPI backend in a Python virtual environment, and the Next.js admin UI. By the end you will have a working import pipeline and a seeded catalog you can browse immediately.

​
Prerequisites

Make sure the following tools are installed before you begin.

Docker Desktop

Required for PostgreSQL 16 and the n8n automation engine. Any recent version works.

Python 3.12

The backend requires exactly Python 3.12. Use pyenv or your system package manager.

Node.js 20+

Required for the Next.js 15 admin UI and the n8n-nodes-onprintshop package build.

​
Step 1: Clone and configure environment variables

1

Clone the repository

git clone https://github.com/VisualGraphxLLC/API-HUB.git
cd API-HUB
2

Copy the backend environment file

cp .env.example .env
Open .env and fill in the required values:
# Database — matches the Docker Compose postgres service defaults
POSTGRES_URL=postgresql+asyncpg://vg_user:vg_pass@localhost:5432/vg_hub

# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
SECRET_KEY=<your-generated-fernet-key>

# Any random 32-character string — used to authenticate n8n → FastAPI calls
INGEST_SHARED_SECRET=<random-32-char-string>

# n8n uses this to reach FastAPI inside Docker networking
API_BASE_URL=http://host.docker.internal:8000
Never commit .env to version control. The SECRET_KEY decrypts all stored supplier credentials — treat it like a private key.
3

Copy the frontend environment file

cp frontend/.env.local.example frontend/.env.local
Verify it contains:
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000

​
Step 2: Start the database and n8n

​
Step 3: Start the FastAPI backend

cd backend
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
The backend runs database migrations automatically on startup. Once you see Application startup complete, confirm it is healthy: 
curl http://localhost:8000/health
Expected response: 
{"status": "ok"}
Leave this terminal open. The --reload flag watches for file changes and restarts automatically.

​
Step 4: Start the Next.js frontend

Open a new terminal: 
cd frontend
npm install
npm run dev
The admin UI will be available at http://localhost:3000.

​
Step 5: Seed demo data

With the backend running, seed the database with demo suppliers and sample products: 
cd backend
source .venv/bin/activate
python seed_demo.py
The seed script creates:
  • Two demo suppliers (one PromoStandards SOAP, one REST)
  • A sample customer with a default markup rule
  • A small set of apparel and print catalog products
Seeded credentials are synthetic and do not connect to any live supplier API. Use them to explore the UI and test import flows without incurring real API calls.

​
Step 6: Trigger your first catalog import

With demo suppliers seeded, trigger a small catalog import to see the full pipeline in action. Replace 1 with the ID of a seeded supplier visible in the admin UI at http://localhost:3000/suppliers. 
curl -X POST http://localhost:8000/api/suppliers/1/import \
  -H "Content-Type: application/json" \
  -d '{"mode": "first_n", "limit": 5}'
Expected response: 
{
  "job_id": "...",
  "supplier_id": 1,
  "mode": "first_n",
  "status": "queued"
}
Watch import progress in the admin UI under Sync Jobs, or poll the health endpoint: 
curl http://localhost:8000/api/sync-jobs/health

​
Verify your setup

After the import completes, check these three surfaces to confirm everything is working end-to-end.

Admin UI

Browse suppliers, products, customers, and sync job history at localhost:3000.

API health

The FastAPI health endpoint returns {"status":"ok"} when the backend and DB are reachable.

n8n dashboard

Inspect workflow executions and cron schedules in the n8n UI at localhost:5678.

​
Run the test suite

cd backend
source .venv/bin/activate
pytest

​
Next steps

Architecture deep dive

Understand how all four systems connect, which routes exist, and why n8n owns external API calls.

Add a real supplier

Connect a live PromoStandards or REST supplier using the admin UI — no code required.

Configure pricing markup

Set per-customer markup rules and test them with the live quote endpoint.

Set up OPS push

Configure the n8n ops-push workflow to sync products into OnPrintShop storefronts.

Build docs developers (and LLMs) love

Get started for freeTalk to us