This is the target reference architecture for the SupplyShore procurement operating system. It is designed to be adopted incrementally from the current stack (see 02-infrastructure/overview), not rewritten from scratch.
pgvector. Avoid a separate MongoDB unless schema flexibility is truly needed. ┌────────────────────────────────────────────┐
│ INTERNET │
└────────────────┬───────────────────────────┘
│ HTTPS (Traefik)
▼
┌───────────────────────────────────────────────────────────────────────┐
│ TRAEFIK (reverse proxy / TLS) │
└───┬──────────┬────────────┬──────────────┬──────────────┬─────────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
crm.* app.* api.* workflow.* (future) portal.*
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐ ┌───────────────┐
│EspoCRM │ │Frontend│ │ Backend │ │ n8n │ │ Buyer/Supplier│
│ (CRM) │ │(Next.js│ │ (FastAPI │ │ (automation│ │ Portal │
│ │ │/React) │ │ /Django)│ │ glue) │ │ (future) │
└───┬────┘ └────────┘ └────┬─────┘ └─────┬──────┘ └───────────────┘
│ │ │
▼ ▼ ▼
┌───────────────────────────────────────────────────────────────┐
│ PostgreSQL (pgvector) — system of record │
│ operational tables + vector embeddings + supplier graph │
└───────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Search │ │ AI / Agents │ │ Worker / Queue │
│ (Typesense/ │ │ (LangGraph / │ │ (Temporal / │
│ Meilisearch) │ │ OpenAI SDK) │ │ Redis/RQ) │
└──────────────┘ └──────┬───────┘ └────────┬─────────┘
│ │
▼ ▼
Vector store (pgvector) Web scraping /
+ embedding API research executors
| Option | Verdict | Notes |
|---|---|---|
| Next.js (React) | ✅ Recommended | SSR/SSG, API routes, huge ecosystem, Vercel-style patterns. |
| React + Vite (SPA) | ✅ Good | Simpler; pair with a separate backend. |
| Tailwind CSS | ✅ Use | Utility CSS, fast UI dev. |
| shadcn/ui | ✅ Use | Copy-paste component library on Radix + Tailwind; ideal for internal tools & portals. |
Recommendation: Next.js + TypeScript + Tailwind + shadcn/ui for both the public site and the buyer/supplier portal. For quick internal dashboards/ops UIs, Appsmith/ToolJet or Streamlit (Python) are faster to ship (see 07-research/github-projects).
| Option | Verdict | Notes |
|---|---|---|
| FastAPI | ✅ Recommended | Async, typed, auto-OpenAPI docs, first-class for AI/webhook integrations, Python (shares ecosystem with scraping/AI). |
| Django + DRF | ✅ Strong | Batteries included (ORM, admin), mature. Use if heavy CRUD/admin is needed. |
| NestJS | ✅ Good | TypeScript, structured DI, good if the team prefers TS end-to-end. |
| Next.js API routes | ⚠️ For light glue only | Not a full backend for the AI/data layer. |
Recommendation: FastAPI as the primary backend API (integrates best with LangChain/LangGraph/Crawlee-python/AI and n8n webhooks). Keep Node/Next.js for frontend concerns.
| Option | Verdict | Notes |
|---|---|---|
| PostgreSQL + pgvector | ✅ Recommended | Single store for relational + vector search; avoids a separate vector DB early. |
| MongoDB | ⚠️ Optional | Only if supplier dossier JSON becomes extremely heterogeneous; otherwise Postgres JSONB suffices. |
| Elasticsearch | ⚠️ Heavy | Powerful but memory-hungry; not ideal on 4 GB. |
| Meilisearch / Typesense | ✅ For search | Lighter, faster-to-run standalone search engines (see Search Layer). |
Recommendation: PostgreSQL as system of record with pgvector for embeddings. Add a dedicated search engine only when supplier count grows past Postgres full-text comfort.
| Option | Verdict | Notes |
|---|---|---|
| n8n | ✅ Recommended for glue | Already installed; visual; good for CRM sync, scraping triggers, notifications, light orchestration. |
| Temporal | ✅ Recommended for durable business processes | Durable, retryable, long-running workflows (RFQ lifecycle, order/fulfillment, multi-step research). Higher learning curve (Go/TS/Python SDK). |
| Prefect / Airflow | ⚠️ Data-pipeline focus | Overkill for business workflow glue; keep in mind for heavy scheduled data pipelines. |
| Windmill | ✅ Good lightweight | Script→workflow→UI; a solid n8n alternative. |
Recommendation: n8n for automation glue today. Introduce Temporal for anything that must survive restarts and resume (long research jobs, order/fulfillment state machines) once that complexity appears.
See full analysis in 03-product/ai-agents. Short verdict:
| Option | Verdict | Notes |
|---|---|---|
| Meilisearch | ✅ Great default | Typo-tolerant, fast, easy self-host, good for supplier/product search. |
| Typesense | ✅ Great | Similar; excellent typo tolerance and speed. |
| Elasticsearch | ⚠️ When very large | Full-featured, but heavy ops. |
Recommendation: Meilisearch for supplier/product/part search UI. Keep Postgres full-text + pgvector for the structured/vector path.
Supplier Discovery & Enrichment (async):
Source (Alibaba/1688/directories/customs)
→ n8n / Crawlee scrapers (scheduled)
→ enrichment workers (LLM normalize + company data + scoring)
→ Supplier master in Postgres (+ vectors)
→ EspoCRM Supplier record (sync)
→ Typesense index (searchable)
Buyer Request → Quote (semi-automated):
Buyer RFQ (portal / email / CRM)
→ n8n parses & classifies
→ AI agent drafts matching suppliers + research brief
→ Sourcing agent reviews/approves
→ RFQ sent to suppliers (email/n8n)
→ Quotes captured → comparison in CRM
Order → Logistics → QC (durable, Temporal):
Order created (CRM)
→ Temporal workflow: milestones, docs, approvals
→ Logistics/tracking API sync
→ QC/inspection trigger
→ Buyer updates + invoice
Phase A (today): Single Linode — Traefik + EspoCRM + n8n + Postgres.
Phase B (first AI/automation workloads): Same Linode for CRM/DB, add a second small Linode for n8n + AI worker + scraping (isolates memory-hungry workloads). Optionally add a managed Postgres to take DB pressure off the app node.
Phase C (product platform):
Provisioning: keep everything in Docker Compose with labeled services (Traefik auto-routes). Consider Portainer for simple container management (07-research/github-projects). Add Terraform only when the fleet grows beyond 2–3 nodes.
| Attribute | Target |
|---|---|
| Availability | 99.5%+ for CRM; graceful degradation for AI (async) |
| Backup | Automated nightly; tested restore ≤ 24h |
| Security | TLS everywhere, secrets manager, least-privilege (see 04-security/security) |
| Observability | Central logs (n8n + app) + uptime alerts; Langfuse for AI tracing (07-research/github-projects) |
| Cost | Remain ≤ $80–120/mo through Phase B |
| Data export | Every dataset (suppliers, quotes, orders) exportable to CSV/JSON at any time |