# steeezzy/forefront-latest architecture

> Architecture diagram of the GitHub repository steeezzy/forefront-latest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steeezzy/forefront-latest
- Repository: https://github.com/steeezzy/forefront-latest

## Overview

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
     - WhatsApp
     - Facebook Messenger
     - Instagram
     - email
     - 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: [`forefront-backend/src/modules`](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/modules) (Domain modules), [`src`](https://github.com/steeezzy/forefront-latest/tree/main/src) (Next.js app), [`forefront-backend/src/app.ts`](https://github.com/steeezzy/forefront-latest/blob/main/forefront-backend/src/app.ts) (Fastify server), [`forefront-backend/src/config`](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/config) (Config layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js control plane"]
  node_next_app["Next.js app<br/>frontend shell"]
  node_bff_routes["API routes<br/>BFF routes"]
  node_panel_ui["Panel UI<br/>product console"]
  node_domain_ui["Domain UI<br/>specialized views"]
end

subgraph group_backend["Fastify core"]
  node_backend_app["Fastify server<br/>API server<br/>[app.ts]"]
  node_backend_modules["Domain modules<br/>route modules"]
  node_ai_rag{{"AI + RAG<br/>llm substrate"}}
  node_workflow_engine{{"Orchestration engine<br/>automation runtime"}}
  node_channel_ingest["Channel ingress<br/>webhooks/channels"]
  node_integrations["Integrations<br/>connectors"]
  node_jobs_queues["Jobs + queues<br/>async processing"]
  node_config_runtime["Config layer<br/>runtime config"]
end

subgraph group_embed["Embedded surfaces"]
  node_widget["Widget build<br/>embed client"]
  node_public_bundle["Public bundle<br/>served asset<br/>[widget-bundle.js]"]
  node_shopify_ext["Shopify extension<br/>storefront embed"]
end

subgraph group_infra["Shared infrastructure"]
  node_postgres[("PostgreSQL<br/>primary datastore")]
  node_redis[("Redis<br/>cache/queue<br/>[redis.ts]")]
  node_templates_industries["Templates"]
end

node_next_app -->|"calls"| node_bff_routes
node_next_app -->|"renders"| node_panel_ui
node_next_app -->|"renders"| node_domain_ui
node_bff_routes -.->|"proxies"| node_backend_app
node_backend_app -->|"hosts"| node_backend_modules
node_backend_modules -->|"uses"| node_ai_rag
node_backend_modules -->|"orchestrates"| node_workflow_engine
node_backend_modules -->|"ingests"| node_channel_ingest
node_backend_modules -->|"syncs"| node_integrations
node_backend_modules -->|"enqueues"| node_jobs_queues
node_backend_app -->|"loads"| node_config_runtime
node_config_runtime -->|"connects"| node_postgres
node_config_runtime -->|"connects"| node_redis
node_channel_ingest -->|"triggers"| node_workflow_engine
node_integrations -->|"persists"| node_postgres
node_ai_rag -->|"reads/writes"| node_postgres
node_workflow_engine -->|"runs on"| node_jobs_queues
node_jobs_queues -->|"uses"| node_redis
node_widget -->|"builds"| node_public_bundle
node_shopify_ext -->|"uses"| node_integrations
node_widget -.->|"sends events"| node_channel_ingest
node_templates_industries -->|"powers"| node_domain_ui
node_templates_industries -.->|"seeds"| node_backend_modules

click node_next_app "https://github.com/steeezzy/forefront-latest/tree/main/src"
click node_bff_routes "https://github.com/steeezzy/forefront-latest/tree/main/src/app/api"
click node_panel_ui "https://github.com/steeezzy/forefront-latest/tree/main/src/app/panel"
click node_domain_ui "https://github.com/steeezzy/forefront-latest/tree/main/src/components"
click node_backend_app "https://github.com/steeezzy/forefront-latest/blob/main/forefront-backend/src/app.ts"
click node_backend_modules "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/modules"
click node_ai_rag "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/services/rag"
click node_workflow_engine "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/services/workflow"
click node_channel_ingest "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/webhooks"
click node_integrations "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/services/shopify"
click node_jobs_queues "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/workers"
click node_config_runtime "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/config"
click node_postgres "https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/migrations"
click node_redis "https://github.com/steeezzy/forefront-latest/blob/main/forefront-backend/src/config/redis.ts"
click node_widget "https://github.com/steeezzy/forefront-latest/tree/main/widget/src"
click node_public_bundle "https://github.com/steeezzy/forefront-latest/blob/main/public/widget-bundle.js"
click node_shopify_ext "https://github.com/steeezzy/forefront-latest/tree/main/shopify-app/extensions/theme-app-extension"
click node_templates_industries "https://github.com/steeezzy/forefront-latest/tree/main/templates/industries"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_next_app,node_bff_routes,node_panel_ui,node_domain_ui toneBlue
class node_backend_app,node_backend_modules,node_ai_rag,node_workflow_engine,node_channel_ingest,node_integrations,node_jobs_queues,node_config_runtime toneAmber
class node_widget,node_public_bundle,node_shopify_ext toneMint
class node_postgres,node_redis,node_templates_industries toneRose
```

## Components

### Next.js control plane

Admin UI, onboarding, dashboards, and BFF routes in the main frontend app.

- [Next.js app](https://github.com/steeezzy/forefront-latest/tree/main/src): frontend shell · Main product UI with dashboard, onboarding, settings, and embedded admin experiences. · `src`
- [API routes](https://github.com/steeezzy/forefront-latest/tree/main/src/app/api): BFF routes · Frontend-local routes for auth sync, chat, templates, industries, and backend proxying. · `src/app/api`
- [Panel UI](https://github.com/steeezzy/forefront-latest/tree/main/src/app/panel): product console · Workspace dashboard, inbox, flows, automation, analytics, billing, and settings screens. · `src/app/panel`
- [Domain UI](https://github.com/steeezzy/forefront-latest/tree/main/src/components): specialized views · 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](https://github.com/steeezzy/forefront-latest/blob/main/forefront-backend/src/app.ts): API server · Backend entrypoints and server bootstrap for the core application. · `forefront-backend/src/app.ts`
- [Domain modules](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/modules): route modules · Route-per-module business capabilities for auth, workspaces, customers, chat, tickets, billing, and more. · `forefront-backend/src/modules`
- [AI + RAG](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/services/rag): llm substrate · LLM services, embeddings, document ingestion, vector search, reranking, guardrails, and handoff logic. · `forefront-backend/src/services/rag`
- [Orchestration engine](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/services/workflow): automation runtime · Workflow execution, scheduling, node registries, recovery, triggers, and worker-backed automation. · `forefront-backend/src/services/workflow`
- [Channel ingress](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/webhooks): webhooks/channels · Inbound webhook and channel normalization for chat, email, WhatsApp, Messenger, Instagram, voice, and SMS. · `forefront-backend/src/webhooks`
- [Integrations](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/services/shopify): connectors · Provider abstractions and sync logic for Shopify, CRM, marketing, analytics, Slack, Zapier, and support tools. · `forefront-backend/src/services/shopify`
- [Jobs + queues](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/workers): async processing · Campaign workers, automation workers, orchestrator workers, recovery jobs, and execution queues. · `forefront-backend/src/workers`
- [Config layer](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/src/config): runtime config · Centralized environment, database, Redis, and plan configuration. · `forefront-backend/src/config`

### Embedded surfaces

Standalone widget and Shopify storefront extension.

- [Widget build](https://github.com/steeezzy/forefront-latest/tree/main/widget/src): embed client · Standalone embeddable chat/widget bundle used on external sites. · `widget/src`
- [Public bundle](https://github.com/steeezzy/forefront-latest/blob/main/public/widget-bundle.js): served asset · Compiled widget assets served from the main app public directory. · `public/widget-bundle.js`
- [Shopify extension](https://github.com/steeezzy/forefront-latest/tree/main/shopify-app/extensions/theme-app-extension): storefront embed · 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](https://github.com/steeezzy/forefront-latest/tree/main/forefront-backend/migrations): primary datastore · Persistent source of truth for workspaces, conversations, workflows, billing, channels, analytics, and vectors. · `forefront-backend/migrations`
- [Redis](https://github.com/steeezzy/forefront-latest/blob/main/forefront-backend/src/config/redis.ts): cache/queue · Shared cache and queue infrastructure supporting jobs and execution state. · `forefront-backend/src/config/redis.ts`
- [Templates](https://github.com/steeezzy/forefront-latest/tree/main/templates/industries): workspace templates · Industry templates and launch blueprints for rapid workspace setup. · `templates/industries`

## Connections

- 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.
