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.

API-HUB ships as four cooperating services — a FastAPI backend, a Next.js frontend, PostgreSQL 16, and a custom n8n image — all declared in a single docker-compose.yml. A companion docker-compose.override.yml is automatically merged during local development to enable hot-reload and bind-mounted source; production deployments bypass it by passing -f docker-compose.yml explicitly.

​
Services

postgres

PostgreSQL 16-alpine on port 5432. Uses a named pgdata volume for durable storage. The compose healthcheck (pg_isready) gates all dependent services — api and n8n will not start until Postgres is accepting connections.

api

FastAPI backend built from ./backend/Dockerfile (multi-stage, Python 3.12-slim), exposed on port 8000. Reads .env at repo root. In the dev override, uvicorn runs with --reload against the bind-mounted ./backend directory.

n8n

Custom image built from n8n.Dockerfile with the OnPrintShop community node baked in at /opt/custom-nodes. Port 5678. Gated behind the dev profile — it does not start unless you explicitly activate that profile.

frontend

Next.js 15 app on port 3000. In the dev override it runs npm run dev against a bind-mounted ./frontend directory with WATCHPACK_POLLING=true for environments that do not support inotify (WSL2, Docker for Mac).

​
Local Development

The recommended local workflow runs the infrastructure in Docker and the application processes on the host, so you get full debugger access and fast iteration.
1

Start infrastructure

Bring up Postgres and n8n. The dev profile is required to include n8n.
docker compose --profile dev up -d postgres n8n
2

Start the backend

Create a virtual environment, install dependencies, and launch uvicorn with hot-reload.
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
On first boot the lifespan handler runs Base.metadata.create_all to create all tables, then executes every statement in _SCHEMA_UPGRADES. If the database is not yet ready, it retries up to 5 times with a 2-second delay between attempts.
3

Start the frontend

In a separate terminal, install Node dependencies and start the dev server.
cd frontend
npm install
npm run dev
The frontend is available at http://localhost:3000. Set NEXT_PUBLIC_API_URL=http://127.0.0.1:8000 in frontend/.env.local so browser requests reach the backend.
4

(Optional) Seed demo data

Load one supplier, one product, and twelve variants to verify the pipeline end-to-end without a live supplier credential.
cd backend && source .venv/bin/activate
python seed_demo.py

​
Full Stack via Docker

If you prefer everything containerised — including hot-reload — the override file handles it automatically. 
docker compose --profile dev up -d
This starts all four services. The api service uses the dev override command (uvicorn ... --reload) and the frontend service runs npm run dev with source bind-mounted.
The override file (docker-compose.override.yml) is merged automatically whenever you run docker compose from the repo root. To use the production-shaped compose file without dev overrides, pass -f docker-compose.yml explicitly.

​
Production Deployment

In production, pass only the base compose file so the override’s dev settings are not applied. 
docker compose -f docker-compose.yml up -d
The backend Dockerfile is already multi-stage and production-shaped: it installs dependencies into /deps, drops to a non-root app user, and runs uvicorn without --reload.

​
Required Environment Variables

The backend refuses to boot when ENVIRONMENT=production and any of the following variables are missing or empty. Set them in your ECS task definition, Secrets Manager, or equivalent secrets backend before deploying.
VariablePurpose
SECRET_KEYFernet key for EncryptedJSON columns (auth_config, ops_auth_config)
JWT_SECRET_KEYSigning key for auth tokens issued at /api/auth/login
INGEST_SHARED_SECRETShared secret for n8n → FastAPI ingest calls (X-Ingest-Secret header)
ALLOWED_ORIGINSComma-separated CORS origins the browser is permitted to call from
POSTGRES_URLasyncpg connection string for the application database
N8N_WEBHOOK_BASE_URLBase URL n8n’s webhook endpoints are reachable at
API_BASE_URLFastAPI base URL as seen by the n8n container
Missing any of these seven variables when ENVIRONMENT=production raises a RuntimeError at startup and the process exits immediately. The error message lists every missing variable by name.

​
Database Migrations

API-HUB does not use Alembic. Schema changes ship as idempotent ALTER TABLE … IF NOT EXISTS and CREATE INDEX … IF NOT EXISTS statements appended to _SCHEMA_UPGRADES in main.py. Every statement is safe to re-execute, so restarting the application applies any pending changes without a separate migration step.

​
n8n Hosting Options

The OnPrintShop community node must be available to n8n. The n8n.Dockerfile bakes it into the image at build time, so the image is portable across any host that runs Docker.
n8n.cloud Starter is not supported. Community nodes are blocked on that tier. You must use a self-hosted image or upgrade to Pro+.

​
Running Tests

cd backend
source .venv/bin/activate
pytest

Build docs developers (and LLMs) love

Get started for freeTalk to us