How steeezzy/forefront-latest works
1. Repository shape
- This is a monorepo for an AI business automation platform called Questron.
- It contains three major runtime surfaces:
- a Next.js 15 frontend in src/
- a Fastify/Node backend in forefront-backend/
- a standalone widget build in widget/ plus a Shopify app extension in shopify-app/
2. Primary system boundary
- The clearest architectural split is UI/client concerns in Next.js versus stateful business logic in the backend.
- The frontend contains the product dashboard, onboarding, marketing pages, and embedded chat/widget UI.
- The backend owns persistent domain logic, AI orchestration, channel integrations, background jobs, webhooks, and database access.
3. Frontend layer
- The Next.js app drives the user-facing product: dashboard, inbox, chatbot setup, flows, analytics, integrations, settings, billing, and industry/workspace builders.
- src/app/api/* contains local API routes, but src/app/api/proxy/[...path] indicates the frontend often acts as a BFF/proxy to the backend rather than duplicating domain logic.
- The frontend also includes reusable UI systems and domain-specific components for chat, inbox, flows, voice agents, knowledge base, and Shopify settings.
4. Backend application core
- The backend is organized as a Fastify API server with route-per-module structure under forefront-backend/src/modules.
- Domain areas include auth, workspaces, customers, inbox/chat, automation, campaigns, billing, integrations, knowledge/RAG, Shopify, social channels, voice, tickets, analytics, bookings, numbers, and workflows.
- src/app.ts and src/index.ts are the main bootstrapping points, while src/config/* centralizes DB, Redis, env, and plan configuration.
5. Persistent data model
- The backend is heavily schema-driven: the migrations/ folder shows a large evolving PostgreSQL model for workspaces, conversations, knowledge vectors, workflows, campaigns, billing, CRM, bookings, channels, notifications, analytics, and voice/call logs.
- This indicates PostgreSQL is the primary source of truth for product state.
- The presence of vector-related migrations and RAG schema suggests embeddings and semantic search are first-class persisted capabilities, not bolt-ons.
6. AI and RAG subsystem
- The platform’s AI layer is split across services in src/services/llm.ts, claude.service.ts, utils/gemini.ts, and the src/services/rag/ folder.
- RAG is composed of document ingestion, chunking, embeddings, vector search, reranking, guardrails, tool registry, and handoff logic.
- src/modules/chat, src/modules/copilot, src/modules/workflow, and src/modules/orchestrator appear to consume this AI substrate to power support chat, copilots, and workflow execution.
7. Orchestration and automation
- A major backend subsystem is the workflow/orchestration engine:
- src/services/workflow/WorkflowEngine.ts
- src/services/workflow/WorkflowScheduler.ts
- src/services/flow/*
- src/modules/orchestrator/*
- The architecture supports triggers, step execution, node registries, workflow recovery, execution queues, and worker processes.
- This means automation is not just CRUD; it has an execution runtime with resilience and recovery.
8. Real-time communication and inbound channels
- Customer-facing communication enters through multiple channel-specific surfaces:
- web chat/widget
- Facebook Messenger
- Twilio voice/SMS
- Backend webhooks in src/webhooks/ and channel services in src/services/social/, src/services/whatsapp.service.ts, src/services/twilio.service.ts, etc. normalize inbound events into shared conversation/message models.
- The inbox UI then consumes these normalized conversations and can also create tickets, hand off to humans, or trigger automations.
9. Background processing
- The backend offloads work to workers and jobs rather than keeping everything in request/response flows.
- Key background units include campaign workers, automation workers, orchestrator workers, customer sync, lead scoring, reminders, and workflow recovery jobs.
- There is also a queue layer (src/queues/execution-queues.ts) and resilience-oriented migrations, which implies the system is designed for durable asynchronous execution.
10. Integrations and external systems
- Integrations are a major boundary: Shopify, CRM, marketing, analytics, Slack, Zapier, Zendesk, and social platforms are all represented.
- The integration layer has provider abstractions plus field mapping and event services, so external systems are mapped into internal workspace/customer/conversation models.
- Shopify is especially deep: there is backend sync, OAuth, webhooks, metafields, widget script generation, frontend settings pages, and a Shopify app extension for storefront embedding.
11. Domain-specific product verticals
- Several modules indicate specialized vertical capabilities rather than a generic helpdesk:
- voice agents
- bookings and reminders
- medicine dose/compliance tracking
- campaigns and win-back automation
- industry workspace templates
- The tidio-clone-plan/ and templates/industries/ content suggest the product has a templated “workspace builder” model for launching industry-specific experiences quickly.
12. Embedding and customer-facing assets
- The repo contains a dedicated widget package and built assets in public/, indicating a separate embeddable frontend artifact.
- The widget is likely consumed by external customer sites and Shopify storefronts, while the main Next.js app is the admin/control plane.
- This creates a classic split between embedded experience and operator console.
13. State management and shared concepts
- Cross-cutting entities repeated across frontend and backend are: workspace, agent, conversation, customer, ticket, flow, knowledge document, campaign, booking, invoice, visitor, integration, and plan/usage.
- The architecture revolves around a workspace-centric multitenant model where each workspace owns channels, AI settings, knowledge, automations, and billing.
14. Operational tooling
- There are many one-off scripts for seeding, reindexing, testing embeddings, validating workflows, checking usage, and running load/chaos harnesses.
- This suggests the project has substantial operational complexity around AI quality, queue reliability, and data maintenance.
- Deployment targets are split as documented in the README: Vercel for frontend and Render for backend.
15. How to draw the architecture
- A good diagram would place the Next.js admin app on one side, the Fastify API + workers on the other, and PostgreSQL/Redis beneath as shared infrastructure.
- Around the backend, show separate clusters for AI/RAG, automation/orchestration, channel/webhook ingestion, integrations, and billing/usage.
- Add the widget/Shopify embed as an external client surface feeding into the same conversation and knowledge systems as the admin UI.
Main entry points: modules Domain modules · src Next.js app · app.ts Fastify server · config Config layer
Components 18
Next.js control plane
Admin UI, onboarding, dashboards, and BFF routes in the main frontend app.
- Next.js app · Main product UI with dashboard, onboarding, settings, and embedded admin experiences.
src - API routes · Frontend-local routes for auth sync, chat, templates, industries, and backend proxying.
src/app/api - Panel UI · Workspace dashboard, inbox, flows, automation, analytics, billing, and settings screens.
src/app/panel - Domain UI · Chatbot setup, voice agents, industries, templates, pricing, login, and help pages.
src/components
Fastify core
Stateful API, domain services, workers, webhooks, and integrations.
- Fastify server · Backend entrypoints and server bootstrap for the core application.
forefront-backend/src/app.ts - Domain modules · Route-per-module business capabilities for auth, workspaces, customers, chat, tickets, billing, and more.
forefront-backend/src/modules - AI + RAG · LLM services, embeddings, document ingestion, vector search, reranking, guardrails, and handoff logic.
forefront-backend/src/services/rag - Orchestration engine · Workflow execution, scheduling, node registries, recovery, triggers, and worker-backed automation.
forefront-backend/src/services/workflow - Channel ingress · Inbound webhook and channel normalization for chat, email, WhatsApp, Messenger, Instagram, voice, and SMS.
forefront-backend/src/webhooks - Integrations · Provider abstractions and sync logic for Shopify, CRM, marketing, analytics, Slack, Zapier, and support tools.
forefront-backend/src/services/shopify - Jobs + queues · Campaign workers, automation workers, orchestrator workers, recovery jobs, and execution queues.
forefront-backend/src/workers - Config layer · Centralized environment, database, Redis, and plan configuration.
forefront-backend/src/config
Embedded surfaces
Standalone widget and Shopify storefront extension.
- Widget build · Standalone embeddable chat/widget bundle used on external sites.
widget/src - Public bundle · Compiled widget assets served from the main app public directory.
public/widget-bundle.js - Shopify extension · Theme app extension and storefront widget assets for Shopify installations.
shopify-app/extensions/theme-app-extension
Shared infrastructure
Persistent data and runtime infrastructure used across the platform.
- PostgreSQL · Persistent source of truth for workspaces, conversations, workflows, billing, channels, analytics, and vectors.
forefront-backend/migrations - Redis · Shared cache and queue infrastructure supporting jobs and execution state.
forefront-backend/src/config/redis.ts - Templates · Industry templates and launch blueprints for rapid workspace setup.
templates/industries
Connections 23
- Next.js app → API routes: calls · UI actions and forms hit local routes before or instead of direct backend calls.
- Next.js app → Panel UI: renders · The frontend app hosts the product control plane screens.
- Next.js app → Domain UI: renders · The frontend also serves marketing, onboarding, chatbot, and vertical-specific pages.
- API routes → Fastify server: proxies · Proxy and sync routes forward requests into the backend API.
- Fastify server → Domain modules: hosts · The Fastify server mounts the domain route modules.
- Domain modules → AI + RAG: uses · Chat, copilot, workflow, and knowledge modules consume shared AI services.
- Domain modules → Orchestration engine: orchestrates · Automation and workflow routes delegate execution to the orchestration runtime.
- Domain modules → Channel ingress: ingests · Channel-specific modules normalize inbound events into shared models.
- Domain modules → Integrations: syncs · Integration modules map external systems into workspace data.
- Domain modules → Jobs + queues: enqueues · Long-running work is pushed to workers and execution queues.
- Fastify server → Config layer: loads · Server startup depends on env, DB, Redis, and plan configuration.
- Config layer → PostgreSQL: connects · Database configuration points at the primary PostgreSQL store.
- Config layer → Redis: connects · Runtime config also wires queue/cache infrastructure.
- Channel ingress → Orchestration engine: triggers · Inbound messages and events can start automations and handoffs.
- Integrations → PostgreSQL: persists · Connection state, mappings, sync metadata, and workspace configuration live in Postgres.
- AI + RAG → PostgreSQL: reads/writes · Knowledge docs, embeddings, vectors, and conversation state are persisted.
- Orchestration engine → Jobs + queues: runs on · Execution and recovery depend on asynchronous job workers.
- Jobs + queues → Redis: uses · Queues and worker coordination use Redis infrastructure.
- Widget build → Public bundle: builds · The widget package produces embeddable assets served by the main app.
- Shopify extension → Integrations: uses · Storefront embedding relies on Shopify sync, OAuth, and webhook integration services.
- Widget build → Channel ingress: sends events · Embedded customer interactions feed the same conversation ingestion path.
- Templates → Domain UI: powers · Industry templates feed workspace builders and launch experiences.
- Templates → Domain modules: seeds · Template definitions align with backend orchestrator and workflow capabilities.