Via Platform — User-Level Features by Microservice

Generated: June 15, 2026
Scope: User-facing capabilities across the Via / Webforge platform microservices
Audience: Product, engineering, and onboarding teams

---

Table of Contents

1. Platform Overview
2. Architecture & Service Map
3. User Personas
4. viamerchantapp2.0 — Merchant Portal
5. viaconsole — Console / Webforge Console
6. viaassistant — AI Merchant Assistant
7. viacore — Core Backend
8. bhs — Business Health Score Application
9. viadomain — Domain Service
10. viagenai — AI Generation Service
11. viasocketserver — Real-Time Messaging Bus
12. vianotificationcenter — Notification Service
13. Cross-Service Workflows
14. Feature Flag Matrix
15. Service Port Reference

---

Platform Overview

The Via platform is a distributed system of backend microservices plus client applications that together provide small-business merchants with:

• AI-generated websites and onboarding
• Lead capture and CRM
• SMS messaging and phone forwarding
• Appointment scheduling and reminders
• Estimates, invoices, and payments
• Business health scoring and growth coaching
• Competitive market intelligence
• Custom domain purchase and DNS management
• AI-powered merchant assistant

Most services are API-only backends with no end-user UI. The primary merchant experience is delivered through viamerchantapp2.0 (merchant portal), bhs (Business Health Score — embeddable coaching UI), and viaconsole (staff console + published merchant sites + onboarding).

Services discover each other via environment-injected URLs and JWT tokens, coordinated through the shared client library @stewopf/viaclientapis.

---

Architecture & Service Map

flowchart TB
    subgraph users [User Entry Points]
        Merchant[Merchant]
        Staff[Staff / Ops]
        Prospect[Prospective Merchant]
        Visitor[Site Visitor]
        Customer[End Customer]
    end

    subgraph apps [Client Applications]
        MA[viamerchantapp2.0 :8080]
        BHS[bhs :3000]
        CON[viaconsole :9000]
    end

    subgraph ai [AI Services]
        ASST[viaassistant :4200]
        GENAI[viagenai GenAI :4000]
        CONCIERGE[viagenai Concierge :4100]
    end

    subgraph core_platform [Core Platform]
        CORE[viacore :6000]
        DOM[viadomain :5500]
        SOCK[viasocketserver :6500]
        NC[vianotificationcenter :3080]
    end

    subgraph external [External]
        Twilio[Twilio]
        Plaid[Plaid]
        AWS[AWS Route53 / S3 / WorkMail]
        OpenAI[OpenAI]
    end

    Merchant --> MA & BHS
    Staff --> CON
    Prospect --> CON
    Visitor --> CON
    Customer --> CON & CORE

    MA --> CON & CORE & ASST & SOCK & NC & BHS
    BHS --> CORE & CON & GENAI
    CON --> GENAI & CORE & DOM & MA & SOCK
    ASST --> MA & CON
    CORE --> DOM & GENAI & MA & SOCK & NC
    NC --> CORE & CON
    GENAI --> CON & CORE & MA
    CONCIERGE --> CON

    CORE --> Twilio & Plaid & AWS
    DOM --> AWS
    GENAI --> OpenAI
    ASST --> OpenAI

---

User Personas

Persona	Primary Surface	What They Do
Merchant	viamerchantapp2.0	Manage business, leads, messages, calendar, billing, website
Prospective Merchant	viaconsole /onboarding	Self-service signup, AI site preview, checkout
Staff / Ops	viaconsole /builder	Tenant CRUD, reports, domains, CMS, NLQ
Site Visitor	Published merchant sites	View site, submit contact form, book appointments
End Customer	SMS, public invoice/estimate links	Receive reminders, pay invoices, text merchant
OPF Mobile User	viamerchantapp2.0 OPF routes, bhs	Onboard from One Park Financial app, view BHS score and Growth Coach
OPF / Salesforce Merchant	bhs (standalone or iframe)	Connect Plaid, view score, Ask Coach, build website via Console

---

1. viamerchantapp2.0 — Merchant Portal

Path: /Users/snickolas/Projects/viamerchantapp2.0
Type: Single deployable application (Next.js 16 + Express 5 BFF)
Port: 8080
Version: 5.1.0

This is not a microservices monorepo. It is the unified merchant portal that aggregates all platform backends into one cohesive UI with authentication, feature flags, and rate limiting.

Authentication & Account Setup

Feature	Route / API	Description
Log in	POST /user/login	Email/password authentication via Console
Session check	GET /user/session	Verify active session
Email verification	POST /user/verify-email	Confirm email address
Privacy policy acceptance	POST /user/confirm/policy	Accept terms before use
Forgot/reset password	POST /user/forgot-password, /update-password	Password recovery flow
Post-checkout setup	POST /user/setup-account	Complete account after shop purchase
Guest/demo access	GET /user/guest	Limited access for onboarding users
Log out	GET /user/logout	End session

Dashboard (Overview)

Feature	Description
Growth overview	Website cards, recent leads, performance widgets
Onboarding wizard	Assign Via phone, domain search, services offered
"What's New" announcements	Console-driven product update modal
Quick access to Via Assistant	When HELP_SYSTEM feature flag enabled
Account setup modal	Triggered after shop checkout

Lead Center (Contacts / CRM)

Feature	API	Description
Search/filter/paginate contacts	POST /api/v1/report/leads	Full CRM list with filters
View/edit/delete lead	PUT/DELETE /api/v1/lead/:leadId	Individual lead management
Bulk CSV import	POST /api/v1/leads/bulkimport	Import up to 50MB CSV
Export leads	POST /api/v1/report/leads/export	Download lead data
New leads today	GET /api/v1/report/leads/new-today	Dashboard widget count
Phone lookup for Messages	POST /api/v1/report/leads/by-phones	Enrich SMS threads with contact info
Native contact sync	GET /api/v1/leads/for-device-sync	Sync with phone contacts (MOBILE flag)
Website visit analytics	/client-center/website-visits	Visitor traffic charts
Form submissions	/client-center/form-submissions	Web form lead log
Phone call logs	/client-center/phone-calls	Inbound call history

Upstream: Via Core (lead storage), Console (tenant context)

Messages (SMS)

Feature	API	Description
View conversation threads	GET /api/v1/sms/threads	SMS inbox
Read thread messages	GET /api/v1/sms/threads/:threadId/messages	Message history
Send SMS / MMS	POST /api/v1/sms/send, /upload-attachment	Outbound messaging
Mark messages read	PATCH single or bulk	Read status management
Delete message/thread	DELETE routes	Soft delete conversations
Real-time inbox updates	WebSocket via Socket Server	Live refresh on new SMS
Schedule appointment from chat	In-UI flow → Calendar APIs	Book from conversation
Create client from unknown number	Lead create via Core	Add new contact
AI SMS replies	Internal webhook from Core	Automated assistant responses

Upstream: Via Core (Twilio), Console (Via phone), Socket Server, S3 (MMS), viaassistant (optional)

Calendar & Appointments

Feature	API	Description
Manage calendars	CRUD /api/v1/calendars	Create/edit/delete calendars
Set availability	freeTimeOverlays on calendar	Block/unblock time slots
View appointments	GET /api/v1/appointments?from=&to=	Month/week/list views
Create/edit/cancel appointments	POST/PUT/DELETE /api/v1/appointments	Full appointment lifecycle
Import client from Lead Center	Links leadId	Pre-fill contact from CRM
Overlap detection	Server-side validation	Prevent double-booking
Send reschedule notifications	POST /api/v1/appointments/:id/notify-reschedule	Manual customer notice
Automated reminders	Cron → Notification Center	24h/1h SMS reminders
Public booking	POST /api/v1/appointments/public	External booking via JWT
Native calendar sync	POST /api/calendar/sync	Phone calendar integration
View free slots	GET /api/v1/tenant/calendar/free-time	Availability for booking

Local storage: MongoDB (calendars, appointments). Lead data from Core.

Estimates & Invoices

Feature	API	Description
List estimates/invoices	GET /api/v1/estimate, /api/v1/invoice	Document list with status filters
Create/edit/delete	POST, DELETE	Full CRUD
Next document number	GET .../next-number	Auto-increment numbering
Download/publish PDF	GET .../pdf, POST .../publish-pdf	PDF generation to S3
Email to customer	POST .../send-email	Send with PDF attachment
Share via WhatsApp	Public share URLs	Customer-facing links
Convert estimate → invoice	POST /api/v1/estimate/:id/convert	One-click conversion
Upload business logo	POST /api/v1/invoice/logo-upload	Branding for documents
Public customer view	/public/invoice/:shareToken	Unauthenticated PDF access

Upstream: Via Core (document storage), S3 (PDFs). Gated by INVOICES_ENABLED.

Via Assistant & Help System

Feature	API	Description
Chat with Via Assistant	POST /api/v1/assistant/messages	Natural language AI chat
View/clear chat history	GET/DELETE /api/v1/assistant/history	Conversation management
Rate responses	PATCH /api/v1/assistant/messages/:turnId/feedback	Thumbs up/down
FAQ search	Agentic: help.searchFaq	Product help
Walkthroughs	Agentic: help.getWalkthrough	Step-by-step UI guides
Submit support ticket	Agentic: help.createTicket	Create ticket
Full-page chat	/assistant route	Dedicated assistant page

Upstream: viaassistant. Gated by HELP_SYSTEM.

Agentic Chat APIs (Assistant Backend)

Machine-facing APIs that viaassistant calls to execute merchant operations:

Domain	Commands
Appointments	search, create, update, cancel, freeTime, resolveCustomer, processReminders
Clients	list, get, create, update, delete, resolve, addNote
Invoices	list, create, sendEmail, markPaid, getPdf, …
Estimates	list, create, convertToInvoice, sendEmail, …
Help	walkthrough, FAQ, ticket, contact options
Competitive	listCompetitors, saveReport, discoverCompetitors

Gated by AGENTIC_CHAT.

Competitive Insights

Feature	API	Description
Manage tracked competitors	CRUD /api/v1/competitive/competitors	Add/edit competitor list
View latest market report	GET /api/v1/competitive/reports/latest	Saved analysis
Generate on-demand report	POST /api/v1/competitive/reports/generate	AI research (3/day limit)

Upstream: viaassistant + Tavily web search. Gated by COMPETITIVE_LISTENING.

My Website & Editor

Feature	Description
View owned websites	Console site summary with thumbnails
Edit website	Redirect to Easyblocks editor
Generate/publish/translate pages	Console page APIs
Domain search & assignment	Onboarding and settings flows

Upstream: Via Console (website builder/CMS)

Business Health Score (Via Score)

Feature	Description
View BHS dashboard	Embedded iframe from bhs app (BHS_URL)
Calculate/refresh score	Core BHS APIs via Plaid (computed in viacore)
AI commentary	Core + viagenai narrative
Score history charts	Historical trend visualization in bhs Summary panel
Plaid bank linking	bhs Plaid connect flow → Plaid Vault OAuth
OPF mobile variants	Dedicated OPF score/setup routes → bhs embed

Upstream: bhs (UI), Via Core (score computation), viagenai (commentary), Plaid, Salesforce (OPF)

Shop, Checkout & Billing

Feature	Description
Browse marketplace products	Domains, email hosting, plans
Add to cart, checkout	Payment flow via Core/Apex
Manage payment methods	Card/ACH CRUD
View plan & payment history	Account endpoints
Download receipts	Client-side PDF generation

Configuration & Account Settings

Feature	Description
Edit business profile	Name, address, timezone, language
Change password	Via Console
Configure Via phone / forwarding	Phone assignment and call routing
Services offered list	Business service catalog
Mobile device sync preferences	Contacts/calendar sync settings
Custom logo (invoices)	Branding upload

OPF (One Park Financial) Mobile Flows

Feature	Description
Onboard from OPF Salesforce ID	Transfer route creates/links tenant
Mobile WebView login	Dedicated mobile authentication
Return to OPF app	Native bridge closeWebView()

Notifications & Announcements

Feature	Description
View unread notifications	Header notification drawer
Dismiss notification	Per-notification dismiss
"What's New" product updates	Console announcements modal

---

2. viaconsole — Console / Webforge Console

Path: /Users/snickolas/Projects/viaconsole
Type: Single deployable service (Express 5)
Port: 9000
Version: 1.2.2

The Console is the orchestration layer and staff UI for the Via platform. It stores tenants, sites, pages, and content in MongoDB, and calls external microservices for AI, payments, domains, and leads.

Staff Builder Home (/builder)

Staff landing page (handlebars/views/home.handlebars) — the authenticated ops hub after Okta login (skippable with NO_AUTH=true in dev). Each tile opens a dedicated admin tool.

Builder Home Capabilities

Existing Merchants (/tenant)

Search, open, and manage live merchant accounts. Staff can browse a paginated merchant list, filter by status, open any tenant profile, edit business details, trigger AI website generation, assign ViaPhone numbers, manage custom domains, import records from GoHighLevel or HubSpot, sync CRM data, and expunge dormant accounts.

Create a Merchant (/tenant?create=true)

Manually onboard a new merchant without the public self-service flow. Staff enter company profile, contact info, industry, timezone, branding, and optional website shell — then proceed to site creation or AI generation from the tenant editor.

View Reports (/reports)

Operations dashboard for platform health and growth metrics. Two views:

Live Metrics dashboard (/reports — modern UI):

• Real-time KPIs via Socket Server: active website visitors, merchants logged into the merchant app, and staff viewing the dashboard
• Total merchants and leads with breakdowns by status (clickable to drill into lists)
• Daily merchant app login trend chart
• Salesforce-linked merchant counts and new-Salesforce-tenant-by-day chart
• Plaid / Business Health Score status breakdown for OPF merchants
• Per-merchant BHS table with links to OPF transfer URLs in the merchant app
• Custom domain inventory (merchant, domain, activation status)
• Published website template usage counts
• Lead distribution histogram (how many merchants share the same lead count)
• Dormant tenant expunge candidates list

Classic reports list (/reports alternate layout):

• Real-time activity table (customers, logged-in merchants, dashboard watchers)
• Merchants grouped by status with CSV export link for all leads
• Leads grouped by status (click through to /reports/status?status=)
• Leads grouped by merchant name
• Phone call volume and average call duration
• Production template usage table

Exports & maintenance:

• Export all leads as CSV (/reports/leads/export)
• Export all merchants as CSV (/reports/tenant/export)
• Trigger dormant tenant expunge cycle (/reports/expunge)
• Lead status detail view (/reports/status?status=)

Manage Domains (/domains)

Full custom-domain administration backed by the Domain microservice (Route 53):

• Browse all platform domains with search, pagination, and status filters
• View domains grouped by purchase month/year for reporting
• List and create Route 53 hosted zones; retrieve name server records
• WHOIS lookup for any domain (rate-limited)
• Slug audit — cross-check merchant slugs vs. domain records to find mismatches
• Domain troubleshoot — diagnostic report (WHOIS, DNS, SSL, load balancer, tenant alignment) returned as markdown
• Per-tenant domain assign/release is also available from the tenant editor

VIA AMA — Ask Me Anything (/tenant/nlpquery)

Experimental natural-language query tool for staff. Ask plain-English questions about platform data and receive answers without writing MongoDB queries manually.

What staff can do:

• Type a question in the prompt (e.g. "How many tenants are LINKED in Plaid?")
• Run NLQ aggregate queries that translate English → MongoDB aggregation pipelines
• View results as interactive tables and charts (bar, pie, line)
• Export results as JSON or CSV
• Use example prompts: Plaid status counts, distinct industries, tenants with published pages
• Toggle helper panels and layout modes for demos

Example questions:

• "Group tenants by Plaid status and return the count for each status"
• "Count distinct industries for tenants"
• "Tenants with published pages"

API endpoints (also callable directly): POST /tenant/nlq, /tenant/nlq/run, /tenant/nlq/aggregate

Manage Call Block List (/call-blocklist)

Platform-wide inbound spam caller management. Blocked numbers are stored in Core and applied to all ViaPhone call routing.

What staff can do:

• Search and paginate the blocklist
• Add a phone number with an optional note (max 50 characters)
• Edit notes on existing entries
• Remove numbers from the blocklist
• US numbers are normalized to +1 E.164 format automatically

Use case: stop repeat spam or robocall sources from reaching merchant forwarding numbers.

Manage Content (/content)

Staff CMS for merchant-facing content consumed in the merchant app and onboarding flows.

Content types:

Type	Purpose
announcement	"What's New" product updates shown in the merchant app modal
avatar_video	Video content with caption and thumbnail (S3-hosted)
script	Spoken or read scripts (e.g. for BHS or coaching media)
article	Help articles and educational content
policy	Legal and policy documents

What staff can do:

• Create, edit, publish, and delete content items
• Author bilingual EN/ES versions for all localized fields
• Schedule announcements for future publish dates
• Manage announcement bundles separately (/content/announcements) with automatic publication worker
• Browse S3 buckets and pick video assets from the asset picker
• Rich-text editor for articles and announcements

Merchant consumption: Published content is served via /api/content/list and /api/content/:id; active announcements via /api/announcements/active.

Realtime Sales Pitch (/sales/pitch) — Non-production only

Demo sales presentation tool for closing deals in QA/staging environments. Displays a sample AI-generated growth plan with quarterly action items, business challenges, and mitigation strategies — the same type of content produced by GenAI for real merchant pitch views. Hidden in production (NODE_ENV set).

Note: Per-tenant sales pitches for live merchants are available at /tenant/:id/pitch with real GenAI-generated growth plans.

Builder Home Quick Reference

Tile	Route	Audience
Existing Merchants	/tenant	Staff
Create a Merchant	/tenant?create=true	Staff
View Reports	/reports	Staff / Ops
Manage Domains	/domains	Staff / Ops
VIA AMA	/tenant/nlpquery	Staff (experimental)
Manage Call Block List	/call-blocklist	Staff / Ops
Manage Content	/content	Staff / CMS
Realtime Sales Pitch	/sales/pitch	Sales (non-production)

Merchant (Tenant) Management (/tenant)

Feature	Description
List/search merchants	Paginated search, excludes expunged
Create new merchant	Full profile form
Edit merchant profile	Company name, phone, email, industry, status, timezone, hours, CRM notes, colors, slug
Trigger website generation	AI site build from tenant form
Refresh/sync from CRM	Pull latest CRM data
Import from GoHighLevel	Search by email/phone
Import from HubSpot	Search by email/phone
Expunge merchant	Full data removal
ViaPhone management	Search available numbers, assign forwarding
Sales pitch / growth plan	AI-generated pitch view
Custom domain management	Search, purchase, assign, release domains
Domain email provisioning	Request @customdomain mailbox
Natural-language query (NLQ)	Ask questions in English → Mongo filters/aggregations

Site & Page Editing

Easyblocks Editor (/blocks)

Feature	Route	Description
Open visual editor	GET /blocks/page/:id/edit	Block-based site builder
Render published/preview page	GET /blocks/page/:id	SSR page rendering
AI-regenerate block content	GET /blocks/page/:id/regenerate	Regenerate selected section
Check AI regeneration quota	GET /blocks/page/:id/regeneration-usage	Usage limits
Stock image search	GET /blocks/api/v1/images	Freepik proxy
Publish page	GET /blocks/api/v1/document/:id/publish	Go live

Legacy Section Editor (/page)

Handlebars-based editor for older template sites: edit page metadata, sections (header, banner, services, FAQs, reviews, contact, footer), add/delete sections, image upload, palette selection.

Site-Level GenAI Actions

Action	Description
entire_page	Full AI site generation
entire_page_translate	Translate page content
entire_palette	Regenerate color palette
regenerate_image	Regenerate section image
generate_salespitch	AI sales pitch content

Self-Service Merchant Onboarding (/onboarding)

Public flow for prospective merchants (English/Spanish):

Step	Route	User Action
Start	/onboarding/start	Business name, services, address, email, phone
Generate	/onboarding/generate	AI builds website with progress UI
Preview	/onboarding/preview	Live iframe preview of generated site
Checkout	/onboarding/checkout	Payment, optional domain purchase, account creation
Purchase	POST /onboarding/purchase	Charges via Core/Apex; creates tenant, site, optional domain
Receipt	/onboarding/receipt	Post-purchase confirmation
Dashboard redirect	/onboarding/dashboard/:tenantId	Redirect to Merchant App

Purchase pipeline: CREATE_APEX_ACCOUNT → CREATE_INTERNAL_RESOURCES → PURCHASE_DOMAIN (optional)

Published Merchant Websites (Public)

Feature	Description
View live published site	Hostname-based routing ({slug}.via.site or custom domain)
Custom domain redirect	Platform hostname → active custom domain
Suspended merchant message	Status-based messaging
Contact/lead form	Submit leads → Core
Appointment availability	GET /lead/calendar/free-time → Merchant App calendar
Standalone lead form by slug	GET /lead/slug/:slug
Privacy policy / terms	Static HTML (EN/ES)
Language selection	Cookie-based locale

Merchant Authentication API (/dashboard)

JWT-based auth consumed by Merchant App:

Endpoint	Purpose
POST /dashboard/signUp	Register merchant user
POST /dashboard/login	Email/password login
POST /dashboard/login-via-tenant	Tenant-scoped login
POST /dashboard/verify-email	Email verification
POST /dashboard/forgot-password	Password recovery
POST /dashboard/reset-password	Password reset
POST /dashboard/refreshToken	Token refresh
POST /dashboard/logout	End session
POST /dashboard/confirm/policy	Accept terms

REST API (/api/*)

Consumer-facing API for Merchant App and integrations:

Endpoint	Feature
GET /api/tenant/list, /tenant/:id	List/read tenants
POST /api/tenant/:id	Update tenant
GET /api/tenant/:id/site	Site summary (thumbnail, status, domain)
GET /api/page/:id/generate	SSE: full AI site generation
GET /api/page/:id/translate	Translate page
GET /api/page/:id/publish	SSE: publish page
POST /api/page/:id	Update page content
GET /api/domain/search	Domain availability
POST /api/tenant/:id/viaphone/assign	Assign ViaPhone
GET /api/announcements/active	Active in-app announcement
GET /api/content/list	Published CMS content

Notifications (/api/notification)

Feature	Description
Create/list/update/delete notifications	Per-tenant notification management
Broadcast to all active tenants	Platform-wide announcements
Read/dismiss/unread counts	Notification state tracking

Content Management (/content)

Staff CMS for merchant-facing content:

Content Type	Description
announcement	Product update announcements
avatar_video	Video content for merchants
script	Scripted content
article	Help articles
policy	Legal/policy documents

Features: CRUD, bilingual EN/ES, scheduled publish, S3 video asset picker.

Domain Administration (/domains)

Feature	Route	Description
Domain management UI	GET /domains	Admin dashboard
Paginated domain list	GET /domains/list	Search and filter
Hosted zones list	GET /domains/hosted-zones/list	Route53 zones
Create hosted zone	POST /domains/hosted-zone/:zone/name-servers	DNS setup
Domains grouped by month	GET /domains/grouped	Reporting
Slug audit	GET /domains/troubleshooting/slug-audit	Troubleshooting
Domain troubleshoot	GET /domains/troubleshooting/domain	Diagnostic report
WHOIS lookup	GET /domains/whois	Rate-limited domain lookup

Call Blocklist (/call-blocklist)

Feature	Description
List blocked numbers	Paginated, searchable
Add/update/delete entries	With notes (max 50 chars)
US phone normalization	+1 E.164 format

Upstream: Core spam blocklist API

Reports & Ops (/reports)

Feature	Route	Description
Main dashboard	GET /reports	Merchant counts, leads, phone stats, template usage, Salesforce tenants, Plaid scores, custom domains
Lead status report	GET /reports/status	Lead pipeline view
CSV export leads	GET /reports/leads/export	Full lead export
CSV export merchants	GET /reports/tenant/export	Full tenant export
Expunge dormant tenants	GET /reports/expunge	Cleanup cycle

---

2.5. viaassistant — AI Merchant Assistant

Path: /Users/snickolas/Projects/viaassistant
Type: Single deployable service (Express 5)
Port: 4200
Version: 1.0.0

AI orchestration layer with six internal domain agents that delegate all business operations to viamerchantapp2.0 via agentic HTTP APIs.

HTTP API

Method	Path	Description
POST	/v1/tenants/:tenantId/messages	Send natural-language message; receive AI reply
GET	/v1/tenants/:tenantId/messages/history	Paginated chat history
DELETE	/v1/tenants/:tenantId/messages/history	Clear chat history
PATCH	/v1/tenants/:tenantId/messages/:turnId/feedback	Rate assistant turn (up/down)
POST	/v1/tenants/:tenantId/inbound/sms	Customer SMS → appointment assistant

Message parameters: message, threadId, channel (merchant_chat/inbound_sms), domain (auto/help/appointments/invoices/estimates/clients/competitive), locale (auto/en/es), generateReport (competitive report refresh)

Domain Agents & User Features

Help Agent

User Can Ask / Do	Command
Step-by-step UI walkthroughs	help.getWalkthrough
Search FAQs	help.searchFaq
Get support contact info	help.getContactOptions
Submit support ticket	help.createTicket
Live demos (when AGENTIC_CHAT enabled)	Calendar/invoice previews during walkthroughs

Appointments Agent

User Can Ask / Do	Command
Search appointments by date/customer	appointments.search
View one appointment	appointments.get
Find open/bookable slots	appointments.freeTime
Look up customer in Lead Center	clients.resolve
Book new appointment	appointments.create
Reschedule	appointments.update
Cancel	appointments.cancel
Notify customer of reschedule	appointments.notifyReschedule

Approval workflow: Mutations on inbound SMS channel require merchant "yes" confirmation.

Invoices Agent

User Can Ask / Do	Command
List/search invoices	invoices.list
Get invoice details	invoices.get
Create invoice	invoices.create
Update/delete invoice	invoices.update, invoices.delete
Email invoice (PDF attached)	invoices.sendEmail
Mark paid/cancelled	invoices.markPaid, invoices.markCancelled
Preview next number / generate PDF	invoices.nextNumber, invoices.getPdf

Estimates Agent

User Can Ask / Do	Command
List/search estimates	estimates.list
Create estimate (from Lead Center client)	estimates.create
Update/delete estimate	estimates.update, estimates.delete
Email estimate	estimates.sendEmail
Convert to invoice	estimates.convertToInvoice
Generate PDF	estimates.getPdf

Clients Agent

User Can Ask / Do	Command
Search/list clients	clients.list
Get client profile	clients.get
Resolve by name/nickname/phone	clients.resolve
Add/update/delete client	clients.create, clients.update, clients.delete
Add note to client	clients.addNote
Save nickname/alias	clients.rememberAlias

Competitive Listening Agent

User Can Ask / Do	Command
Web research on competitors/market	Tavily API (local)
Load merchant profile + tracked competitors	competitive.getMerchantContext
List/save discovered competitors	competitive.listCompetitors, competitive.discoverCompetitors
Fetch/save structured analysis report	competitive.getReport, competitive.saveReport
Full dashboard refresh	generateReport: true on /messages

Cross-Cutting Features

Feature	Description
Conversation memory	Short-term (30 turns) + long-term summaries in MongoDB
Domain routing	LLM classifier with regex fallback; default: help
Mutation confirmation	Inbound SMS mutations require merchant approval
Follow-up questions	2–3 suggested next messages after each reply
Bilingual support	English and Spanish throughout
Feedback	Thumbs up/down on assistant turns

---

3. viacore — Core Backend

Path: /Users/snickolas/Projects/viacore
Type: Single deployable service (Express 5)
Port: 6000
Version: 1.1.0

Core backend for Via merchant workflows. No merchant UI — all features consumed via Merchant App, Console, or direct webhooks.

Lead Service (/api/v1/lead)

Feature	Endpoint	Description
Submit lead from website form	POST /:tenantId/:siteId/{:pageId}	Capture contact info
Validate email preflight	GET /preflight?email=	Email validation
List/search leads	POST /:tenantId	Paginated lead list
View a lead	GET /:leadId	Lead detail

Workflow: Upserts by email/phone; statuses NEW → CONTACTED → IN-PROGRESS → COMPLETED; sends merchant notification email; creates appointment if appointmentDate included.

Tenant / Console Service (/api/v1/tenant)

Feature	Endpoint	Description
Create/update tenant plan	POST /plan	Growth plan management
List leads (tenant-scoped)	POST /lead	Filtered lead list
Today's new leads count	GET /lead/newLeadsToday	Dashboard metric
Bulk import leads	POST /lead/bulkimport	CSV import
View/update lead	GET/POST /lead/:leadId	Lead CRUD
BHS score history	GET /scoreHistory	Historical scores
Analytics reports	GET /property/:report	business, visits, leads, phonecalls, demographics

Twilio / SMS / Phone Service (/api/v1/twilio)

Feature	Endpoint	Description
Configure call forwarding	POST /forward	With optional press-1 IVR
Get forward settings	GET /forward/settings	Current routing config
Search available phone numbers	POST /phone/search	By city, state, area code
Purchase Twilio number	GET /phone/:phoneNumber/purchase	Number provisioning
Release number	GET /phone/:phoneNumber/release	Deprovision
Test outbound call	GET /phone/:phoneNumber/test	Verify forwarding
SMS conversation inbox	CRUD /conversation/*	Threads, messages, read/delete
Send SMS/MMS	POST /conversation/send	Outbound messaging
Spam caller blocklist	CRUD /spam-blocklist	Block unwanted callers
Phone preflight validation	GET /preflight?phone=	Number validation

Caller experience (Twilio webhooks): Inbound calls forwarded to merchant; first-call SMS to merchant; lead created from inbound call; inbound SMS ingested; STOP/opt-out handling.

Dev-only UI: BR549 Conversation Tester at /br549 (non-production).

Analytics Service (/api/v1/analytics)

Feature	Description
Create GA property for tenant/site	Google Analytics 4 setup
Delete GA property	Remove tracking
Run custom GA report	Date ranges, metrics, dimensions

Business Health Score (BHS) Service (/api/v1/bhs)

Feature	Endpoint	Description
Get current BHS score	GET /:tenantId/score	Plaid-based score
Score history	GET /:tenantId/score/history	Trend data
AI score commentary	GET /:tenantId/commentary	GenAI narrative (multilingual)
Growth Coach conversation	POST /:tenantId/growth-coach/turn	Persist coaching turns

Mail Service (/api/v1/mail)

Feature	Description
Create mail organization	AWS WorkMail org for merchant
List/create/delete users	Business email management
Automated DNS setup	Background job for domain → DNS → user

Payment & Billing Service (/api/v1/payment)

Feature	Description
Create payment account	Finix/Apex account setup
Manage bank accounts / cards	Payment method CRUD
View/update contact & payment method	Account settings
Payment history	Enriched with order data
Make a payment	Creates order (can include domain)
View/update subscription plan	Plan management
Browse products	Product catalog
View orders	Order history

Domain purchase workflow: Product ID 9 → viadomain suggest → payment → viadomain purchase → console tenant update.

Invoice Service (/api/v1/invoice)

Feature	Description
Full CRUD lifecycle	Create, read, update, delete
Next invoice number	Auto-increment
Download/publish PDF	Playwright rendering → S3
Email invoice to customer	PDF attachment via SendGrid
Public share link	GET /public/:shareToken (no auth)

Statuses: draft, sent, paid, overdue (auto-refreshed).

Estimate Service (/api/v1/estimate)

Same CRUD/PDF/email pattern as invoices, plus:

Feature	Description
Convert estimate to invoice	Idempotent conversion
Public share link	Customer-facing access

Ticket / Support Service (/api/v1/ticket)

Feature	Description
Submit support ticket	Sends email notification

PDF Service (/api/v1/pdf)

Feature	Description
Render receipt PDF	Server-side HTML-to-PDF (Playwright)

---

3.6. bhs — Business Health Score Application

Path: /Users/snickolas/Projects/bhs
Type: Standalone Next.js web application (merchant-facing, embeddable)
Port: 3000 (dev); Docker exposes 8080
Version: 0.3.1

Mobile-first conversational UI that explains a merchant's Business Health Score (300–1000) in plain language. BHS is the presentation and coaching layer — score computation lives in viacore; BHS consumes Core APIs and renders the merchant experience. Embeddable in viamerchantapp2.0 (/via-score), Salesforce, and OPF mobile flows.

Stack: Next.js 16 (App Router), React 19, Tailwind CSS v4, shadcn/ui, OpenAI (Growth Coach), HeyGen (video), PostHog, MongoDB (sessions/coach limits), @stewopf/viaclientapis

Application States (Router-Driven)

The main app at / routes merchants by Plaid/score status:

State	When	User Experience
No tenant	No tenantId in URL or localStorage	Educational landing: what BHS is, how to get a Growth Coach link
Not linked / Link requested	Plaid not connected, no cached score	Blocking Plaid connect flow (chat or standalone ?v=v1)
In progress	Bank linked, score calculating (1–4 min)	Pending score ring, educational metric videos, optional Ask Coach
Linked	Score available	Full Growth Coach + Summary experience (V2 default)

Experience variants: ?v=v2 (default, modern chat + summary), ?v=conversation (legacy), ?v=v1 (standalone summary shells)

Score Understanding (Linked Merchants)

Feature	Description
View current score	Animated score ring (300–1000), label (excellent/good/fair/poor), delta vs previous period
Choose consumption mode	Listen (pre-generated audio), Watch (inline video), or Read (text transcript)
Guided conversation flow	Chat walkthrough: opening score, understanding score, business health story (trend pattern), strengths, growth areas
Full Summary panel	Slide-in dashboard with summary, top strength, room for growth, score history chart (weekly/monthly), all 11 metrics sortable
Metric deep-dive	Tap any metric → audio/video explainer + quick fix suggestion
Chat ↔ Summary toggle	Switch panels; Salesforce embed opens Summary by default
Linked bank accounts	Dropdown showing connected Plaid institutions
Language toggle	English ↔ Spanish (persisted via ?lang= or UI)
Score-ready notification	Toast when polling detects updated score after Plaid return

Plaid Bank Connection

Feature	Description
Connect business bank account	CTA from chat, summary, coach explore, top banner, nudge modal
Complete Plaid OAuth	Redirect to Plaid vault (PLAID_VAULT_URL); brands: OPF (standalone) or VIA (merchant dashboard embed)
Resume incomplete link	LINK_REQUESTED state with "continue secure link" messaging
Non-blocking Plaid nudge	Once-per-session modal if score exists but Plaid shows NOT_LINKED
OAuth callback	/plaid/onboard/complete updates Console Plaid state, redirects to BHS home

Growth Coach / Ask Coach (AI Chat)

When FF_BHS_ASK_COACH enabled (currently hardcoded on):

Feature	Description
Ask free-text questions	About score, metrics, and business health
Suggested chips	e.g. "Why is my [lowest metric] low?", cash flow tips, score improvement
Streamed GPT-4o answers	Grounded in score data + HeyGen script knowledge base
Turn limit	Max 10 coach turns per conversation thread (MongoDB-enforced)
Guardrail refusals	Off-topic or inappropriate questions declined politely (EN/ES)
Turn persistence	Coach turns saved to viacore Growth Coach API

Available in linked V2, linked V1, not-linked, and in-progress waiting states.

Website / Via Onboarding CTAs

For merchants without an existing website (suppressed when hideSiteCta=true or hasWebsite=true):

Feature	Description
Top banner "Build My Site"	Deep link to viaconsole /onboarding?tenantId=&lang=
In-chat website offer	Conversational prompt; Yes → Console onboarding
Bottom toolbar CTA	"No website yet?" prompt on mobile

Not-Linked & In-Progress Experiences

Feature	Description
Onboarding conversation	Explains need for bank connection; mode choice (listen/video/read)
Plaid connect modal	Secure, read-only messaging
Summary with placeholder score	Preview dashboard layout while prompting link
Pending score card	Animated ring while Core computes (~1–4 min)
Explore 11 metric topics	Pre-recorded explainers while waiting
Auto-polling	Refreshes /api/bhs every 15s until LINKED
Timeout handling	After 120s, refresh/retry UI in Summary panel

The 11 Score Metrics

Each metric has name, score (0–100), status, summary, detail, and optional HeyGen video:

Metric	Focus
Average daily balance	Balance stability
Average daily deposits	Incoming cash consistency
Cash flow efficiency	In vs out
Cash runway days	Operating runway
Healthy burn rate	Spending sustainability
Liquidity ratio	Cash vs obligations
Negative days	Near-zero balance days
Positive cash buffer days	Cushion days
Revenue stability score	Month-to-month consistency
Revenue trend (30-day)	Recent revenue direction
Weekly deposit frequency	Deposit regularity

Educational & Trust Content

Feature	Description
FAQ modal	7+ questions (what BHS is, data sources, score factors, funding disclaimers) EN/ES
Disclaimer modal	Legal copy (not financial advice, no funding guarantee)
Score band education	Via HeyGen scripts and chat content

UI Routes

Route	Audience	Description
/	Merchants	Main BHS experience (router-driven states)
/plaid/onboard/complete	Merchants	Plaid OAuth return handler
/health	Ops	Liveness probe
/catalog	Internal	HeyGen catalog manager (Basic Auth)
/test-harness	Dev/QA	Platform integration debugger
/qa-panel	Dev/QA	Mock state control panel
/bhs-portal-2	Prototype	Alternate portal UI (not wired to live Core)

Embed Query Parameters

Used by viamerchantapp2.0, Salesforce, and OPF:

Param	Effect
tenantId	Required merchant identifier
lang=en|es	UI language
hideSiteCta=true	Hides website CTAs; uses Plaid brand VIA (merchant dashboard embed)
hasWebsite=true	Suppresses website builder offers
status=LINKED|NOT_LINKED|IN_PROGRESS|LINK_REQUESTED	Forces initial UI state (QA/debug)

API Endpoints (Merchant-Facing)

Method	Path	Purpose
GET	/link?tenantId=&lang=&brand=	Validate tenant, return Plaid vault URL
GET	/api/bhs?tenantId=&lang=	Full BHS payload + tenant metadata (proxies viacore + viaconsole)
GET	/api/bhs/commentary?tenantId=&lang=	Lazy-load localized narrative copy from Core
GET	/api/bhs/score-history?tenantId=&frequency=	Historical scores from Core
POST	/api/chat	Growth Coach streaming chat (OpenAI GPT-4o)
POST	/api/bhs-session	Engagement session start/end (MongoDB)
GET	/plaid/onboard/complete?token=	Plaid OAuth return

Internal Modules

Module	Purpose
BHSRouter	Central state machine; bootstraps tenant, polls score, routes by status
Score Data API	Proxy to viacore calculateBusinessHealthScore + viaconsole tenant metadata
Plaid Linking	Vault URL generation, Console plaidInformation.status updates
Growth Coach	OpenAI chat with moderation, scope classifier, knowledge base from HeyGen scripts
HeyGen Pipeline	Internal video generation; merchant content served from S3 (viasite-videos bucket)
Session Tracking	MongoDB engagement sessions for analytics and coach threading

Integrations

Project	Integration
viacore	Score calculation, commentary, score history, Growth Coach turn persistence
viaconsole	Tenant metadata (Plaid status, business name, website URL), onboarding deep links, Plaid status updates
viagenai	BHS narrative commentary (via Core)
viamerchantapp2.0	Embeds BHS at /via-score with ?hideSiteCta=true; OPF transfer routes
Plaid Vault	External OAuth for bank linking (PLAID_VAULT_URL)
HeyGen + S3	Pre-recorded metric explainer videos
OpenAI	Growth Coach chat, moderation, scope classification
PostHog	Product analytics, person properties, feature flags
Salesforce	iframe detection forces Summary panel; opportunity fields synced to analytics

Feature Flags

Flag	Effect
FF_BHS_ASK_COACH	Enables Ask Coach UI + /api/chat (currently hardcoded on in code)
FF_ENABLE_TEST_HARNESS	Enables /test-harness in production
NEXT_PUBLIC_BHS_QA_PANEL	Dev-only QA panel button
?hideSiteCta=true	Hide website CTAs; VIA Plaid brand (merchant embed)
?hasWebsite=true	Hide website offers

---

3.5. viadomain — Domain Service

Path: /Users/snickolas/Projects/viadomain
Type: Single deployable service (Express 5)
Port: 5500
Version: 1.0.0

Domain lifecycle management — search, purchase, DNS hosting, SSL certificates, and activation monitoring. No UI in this repo.

Domain Search & Discovery

Feature	Endpoint	Description
Domain suggestions with pricing	GET /domain/suggest?query=	Up to 10 suggestions via Route 53
Domain status	GET /domain/:domain/status	Current provisioning state
Domain info	GET /domain/:domain/info	Registration details
DNS records	GET /domain/:domain/records	Current DNS configuration

Domain Purchase & Lifecycle

Feature	Endpoint	Description
Purchase domain	GET /domain/:domain/purchase?foreignKey=	Start provisioning (tenant ID)
Release domain	GET /domain/:domain/release	Deactivate
Expunge domain	DELETE /domain/:domain/expunge	Full AWS teardown

Lifecycle state machine:

PURCHASE_REQUEST → SUBMITTED → HOSTED_ZONE → DNS_PROPAGATION →
UPDATE_VIA_RECORDS → CERT_UPDATE_REQUEST → HTTPS_PING → SUCCESSFUL

Background watcher pings HTTPS every ~10 min; on activation → webhook to Console.

DNS / Hosted Zone Management

Feature	Endpoint	Description
List hosted zones	GET /domain/hosted-zones	Route53 zones
Create hosted zone	POST /domain/hosted-zones	New DNS zone
Get zone name servers	GET /domain/hosted-zones/:zoneName/name-servers	NS records
Paginated domain list	GET /domain/list	Search and filter
Domains grouped by date	GET /domain/grouped	Reporting

Troubleshooting & Audit

Feature	Endpoint	Description
Slug audit	GET /domain/troubleshooting/slug-audit	Cross-check slugs vs domains
Domain troubleshoot report	GET /domain/troubleshooting/domain?domain=	WHOIS, Route53, ACM, ELB diagnostic

Merchant Domain Purchase Flow

1. Merchant searches names in checkout → viacore calls /domain/suggest
2. Merchant selects domain and pays → viacore calls /domain/:domain/purchase
3. viadomain state machine: register → hosted zone → DNS → ELB alias → cert
4. Domain watcher detects HTTPS live → webhook to Console → tenant updated
5. Merchant site accessible at custom domain

---

4. viagenai — AI Generation Service

Path: /Users/snickolas/Projects/viagenai
Type: Two deployable processes in one repo
Ports: 4000 (GenAI), 4100 (Merchant Concierge)
Version: webforgegenai

No UI in this repo — APIs consumed by Console, Core, and Merchant App.

Service 1: Main GenAI API (:4000)

AI Job Actions

Action	End-User Capability
entire_page	Generate full landing page: Services, About Us, Hero, Reviews, FAQs, Color palette
entire_palette	Generate or refine brand color palette
entire_page_translate	Translate page text blocks (Google Translate)
regenerate_image	Replace section image (service, about-us, hero)
regenerate_aboutus	Regenerate About Us mission text + image
regenerate_service	Regenerate single service name/description + image
regenerate_review	Regenerate customer review
regenerate_faq	Regenerate FAQ Q&A pair
generate_growthplan	8-challenge growth roadmap with quarterly action plan

Additional Endpoints

Endpoint	Description
POST /site/:siteId/genai?action=…	Start AI job for a site
GET /site/:siteId/genai/job/:jobId/status	Poll job progress
GET /api/v1/ai/address/extract	Parse free-text address
POST /api/v1/ai/bhs/commentary	AI narrative on business health score

Job lifecycle: ACTIVE → COMPLETE or ERROR; webhooks fire to Console/MerchantApp/Core on completion.

Image sourcing: Unsplash, Freepik, Pixabay, internal Via photo library, DALL-E 3.

Service 2: Merchant Concierge (:4100)

Rules-first + LLM-routed conversational assistant for micro-merchants.

Endpoint	Description
GET /v1/tenants/:tenantId/profile	Read merchant coaching profile
PUT /v1/tenants/:tenantId/profile	Update profile (goals, revenue, challenges)
POST /v1/tenants/:tenantId/messages	Send chat message; receive coaching reply

Specialist Agents (Hidden from Merchant)

Agent	Triggers	What Merchant Gets
Financial Coach	Cash flow, margin, expenses keywords	Cash flow analysis, margin advice, expense tradeoffs
Competitive Coach	Competitors, pricing, retention keywords	Positioning, local competition, low-cost experiments
Admin Assistant	Checklist, schedule, paperwork keywords	Tasks, drafts, follow-ups

Response structure: Headline, situation summary, this-week actions, 30-day actions, questions, watch-outs, confidence level.

Safety: High-risk topics (tax, legal, IRS, fraud) → escalation to qualified professionals only.

---

5. viasocketserver — Real-Time Messaging Bus

Path: /Users/snickolas/Projects/viasocketserver
Type: Single deployable service (Express 5 + Socket.IO 4)
Port: 6500

Real-time pub/sub infrastructure — no business logic, no production UI.

Server-Side Push API

Endpoint	Description
POST /message	Emit Socket.IO event to one or more rooms

{
  "room": "tenantId",
  "message": "eventName",
  "payload": { "any": "object" }
}

Client Connection Features

Query Param	Effect
room	Join named room
tenantId	Tenant-scoped room
isWebsite=true	Join ALL_SITES + tenant room
isMerchant=true	Join ALL_MERCHANTS + tenant merchants room
isMonitor=true	Join MONITORS room

End-User Impact (Indirect)

End User	Feature Enabled
Merchant	Real-time SMS inbox updates (newSMSMessage event)
Merchant app (general)	Any tenant-room event triggers UI refresh
Website visitors/editors	Live site reload / editor sync
Operators/monitors	Aggregate connection counts

Primary integration: viacore pushes newSMSMessage on inbound Twilio SMS → merchant app's Messages page refreshes without polling.

---

6. vianotificationcenter — Notification Service

Path: /Users/snickolas/Projects/vianotificationcenter
Type: Single deployable service (Express + BullMQ worker)
Port: 3080

Backend notification orchestrator for appointment reminders. No UI — merchant configuration lives in viamerchantapp2.0 calendar settings.

Reminder Management API

Endpoint	Description
POST /reminders/schedule	Schedule BullMQ jobs for appointment reminders
POST /reminders/reschedule	Cancel old jobs, optionally send change notice, reschedule
POST /reminders/cancel	Remove pending reminder jobs
GET /health	Deep check: MongoDB + Redis

End Customer Features (Indirect)

Feature	Channel	Status
Upcoming appointment reminders	SMS (24h and 1h before)	Active when FF_APPOINTMENT_SMS_ENABLED=true
Localized message content	SMS	EN/ES via appointment locale
Personalized placeholders	SMS	customer_name, date, time, business_name, service, location
Appointment-changed notification	SMS	Available via API; merchant app sends separately today
Email reminders	Email	Not scheduled (SMS-only policy)
Push notifications	Push	Not implemented

Merchant Features (via viamerchantapp2.0)

Merchant Action	Effect
Configure reminder templates	Calendar settings → ReminderSettingsModal
Create appointment	Triggers scheduleReminders(appointmentId)
Update/reschedule appointment	Triggers rescheduleReminders(appointmentId)
Cancel/delete appointment	Triggers cancelReminders(appointmentId)
Manually notify customer of reschedule	Merchant app sends directly via Core (bypasses NC)

Reminder configuration: Calendar defaults + appointment overrides; fallback: 24h and 1h SMS. Requires tenant Via phone number.

Reliability Features

Feature	Implementation
Idempotency	Deterministic job IDs + NotificationLog unique keys
Retry strategy	3 attempts, exponential backoff (2s, 4s, 8s)
Feature flag	FF_APPOINTMENT_SMS_ENABLED gates SMS delivery
Fresh data at send time	Re-fetches appointment status before sending

---

Cross-Service Workflows

1. Merchant Onboarding (Prospect → Active Merchant)

Prospect → viaconsole /onboarding/start
         → viagenai (entire_page AI site generation)
         → viaconsole /onboarding/preview
         → viaconsole /onboarding/checkout
         → viacore (Apex payment account + charge)
         → viadomain (optional domain purchase)
         → viaconsole (tenant/site/user created in MongoDB)
         → viamerchantapp2.0 (guest login redirect)

2. Lead Capture (Visitor → Merchant Notification)

Site visitor → viaconsole published site contact form
             → viacore POST /api/v1/lead (createLead)
             → viaconsole notification API (merchant alert)
             → viamerchantapp2.0 Lead Center (view/manage)

3. SMS Conversation Loop

Customer texts Via phone → Twilio webhook → viacore (ingest SMS)
                          → viasocketserver (newSMSMessage to tenant room)
                          → viamerchantapp2.0 Messages (real-time refresh)
Merchant replies → viamerchantapp2.0 → viacore → Twilio → Customer
Optional: inbound SMS → viaassistant → agentic APIs → automated reply

4. Appointment Lifecycle

Merchant creates appointment → viamerchantapp2.0 (MongoDB)
                             → vianotificationcenter (schedule 24h/1h SMS)
                             → BullMQ delayed jobs
At send time → NC re-fetches appointment → viacore SMS → Customer phone

Public booking: Site visitor → viaconsole free-time API
              → viamerchantapp2.0 POST /appointments/public
              → viacore (create lead if new) → NC (schedule reminders)

5. AI Assistant Operation

Merchant types in chat widget → viamerchantapp2.0 /api/v1/assistant/messages
                              → viaassistant (domain routing)
                              → specialist agent (OpenAI tool-calling)
                              → viamerchantapp2.0 /api/v1/agentic-chat/*/execute
                              → viacore / MongoDB (business data)
                              → reply + walkthrough + follow-up questions

6. Invoice/Estimate Workflow

Merchant creates estimate → viamerchantapp2.0 → viacore (estimate CRUD)
Merchant converts to invoice → viacore (convert, idempotent)
Merchant sends email → viacore (PDF via Playwright → S3 → SendGrid)
Customer views public link → viamerchantapp2.0 /public/invoice/:shareToken

7. Domain Purchase

Merchant selects domain at checkout → viacore payment (suggest via viadomain)
                                    → viacore payment success
                                    → viadomain purchase (state machine)
                                    → AWS Route53 + ACM + ELB
                                    → viadomain watcher (HTTPS ping)
                                    → viaconsole webhook (DOMAIN_STATE_CHANGE)
                                    → tenant customDomain.status = ACTIVE

8. Business Health Score

Merchant lands on bhs (/?tenantId=) or viamerchantapp2.0 /via-score (iframe embed)
         → bhs GET /link (validate tenant, Plaid vault URL)
         → bhs GET /api/bhs (proxies viacore + viaconsole)

Not linked: Merchant connects Plaid → Plaid Vault OAuth
         → /plaid/onboard/complete → viaconsole (Plaid status update)
         → bhs polls /api/bhs every 15s (IN_PROGRESS)

Score ready: viacore calculates score (Plaid data) → MongoDB persist
         → viagenai (AI commentary, multilingual)
         → viaconsole (tenant disposition update)
         → bhs LINKED state: score ring, chat walkthrough, Full Summary

Optional: Ask Coach → bhs POST /api/chat (OpenAI) → viacore (persist turns)
Optional: Build My Site → viaconsole /onboarding

---

Feature Flag Matrix

Feature flags are set on tenant.fabric.features (from Console FF_* env vars):

Flag	Services Affected	UI Impact
MESSAGES_ENABLED	viamerchantapp2.0	Sidebar Messages, mobile nav
CALENDAR_ENABLED	viamerchantapp2.0	Appointments calendar
INVOICES_ENABLED	viamerchantapp2.0	Estimates & Invoices module
HELP_SYSTEM	viamerchantapp2.0, viaassistant	Via Assistant widget, /assistant, support live chat
AGENTIC_CHAT	viamerchantapp2.0, viaassistant	Agentic tool APIs, live calendar/billing operations
COMPETITIVE_LISTENING	viamerchantapp2.0, viaassistant	Competitive Insights at /insights/competitive
MOBILE	viamerchantapp2.0	Native device contact/calendar sync (OPF mobile app)
FF_APPOINTMENT_SMS_ENABLED	vianotificationcenter	Actual SMS reminder delivery
HUBSPOT_INTEGRATION	viaconsole	HubSpot deal sync during onboarding
FF_BHS_ASK_COACH	bhs	Growth Coach / Ask Coach AI chat UI
FF_ENABLE_TEST_HARNESS	bhs	Integration test harness in production

---

Service Port Reference

Service	Default Port	Env Variable
viaconsole	9000	CONSOLE_PORT
viagenai (GenAI)	4000	GENAI_PORT
viagenai (Concierge)	4100	CONCIERGE_PORT
viaassistant	4200	ASSISTANT_PORT
viadomain	5500	PORT
viacore	6000	PORT
viasocketserver	6500	SOCKET_PORT
viamerchantapp2.0	8080	MERCHANTAPP_PORT
vianotificationcenter	3080	PORT
bhs	3000	BHS_URL

---

Summary: Where Features Live

User Capability	Primary Service	UI Surface
Self-service signup & checkout	viaconsole + viacore + viadomain	/onboarding/*
AI website build	viagenai	Console editor, onboarding
Edit/publish website	viaconsole	/blocks, /page
View live merchant site	viaconsole	Hostname routing
Merchant dashboard	viamerchantapp2.0	All /dashboard, /messages, etc.
Lead management	viacore	viamerchantapp2.0 Lead Center
SMS messaging	viacore + viasocketserver	viamerchantapp2.0 Messages
Appointments & calendar	viamerchantapp2.0 (MongoDB)	/calendar
Appointment reminders	vianotificationcenter	Automated SMS to customers
Estimates & invoices	viacore	viamerchantapp2.0 billing module
AI merchant assistant	viaassistant	viamerchantapp2.0 widget + /assistant
Competitive insights	viaassistant + viamerchantapp2.0	/insights/competitive
Business health score (computation)	viacore + viagenai	API-only (Core BHS module)
Business health score (UI & coaching)	bhs	Standalone app, embedded at viamerchantapp2.0 /via-score, OPF/Salesforce
Plaid bank linking	bhs + Plaid Vault	bhs Plaid connect flow
Growth Coach (Ask Coach)	bhs + OpenAI	bhs in-app chat; turns persisted to viacore
Score metric explainers	bhs + HeyGen/S3	Pre-recorded audio/video for 11 metrics
Domain purchase & DNS	viadomain	Console onboarding, /domains
ViaPhone provisioning	viacore	Console /tenant/*/viaphone
Staff merchant CRUD	viaconsole	/tenant/*
CMS content	viaconsole	/content
Ops reports	viaconsole	/reports
Real-time updates	viasocketserver	Transparent (Messages inbox)
Payments & billing	viacore	viamerchantapp2.0 shop + settings
Support tickets	viacore + viaassistant	viamerchantapp2.0 /support
Merchant coaching	viagenai Concierge	API-ready (not yet in merchant UI)

---

This document reflects the codebase state as of June 2026 across viamerchantapp2.0, viaconsole, viaassistant, viacore, viadomain, viagenai, viasocketserver, vianotificationcenter, and bhs. For endpoint-level details, refer to each service's route files and @stewopf/viaclientapis client library.