Automation
Architecture

Executive Summary

Serene & Co. enters this Architecture phase with a clear diagnostic in hand: the April 2026 Audit identified $317,000 in annual labor cost concentrated in four workflows — lead intake, post-visit follow-up, membership retention, and monthly reporting — all of which are manual, inconsistent, and directly replaceable by automated systems. This Architecture document translates those findings into a precise technical specification. Every system, pipeline, agent, and integration defined here is derived from a specific audit finding. Nothing is designed speculatively.

The core architectural decision in this engagement is to establish HubSpot as the operational brain of Serene & Co.'s client lifecycle — connected in real time to Vagaro as the system of record for appointments and bookings, and powered by EnFlow OS for automation logic, behavioral scoring, follow-up sequencing, and performance intelligence. The current state, where Vagaro and HubSpot operate as isolated silos with no data flow between them, ends at go-live. From that point forward, every appointment event in Vagaro triggers a corresponding action in the system — no human coordination required.

At the end of Phase 03 Implementation, Serene & Co. will have: a live AI intake agent handling every inbound inquiry across Instagram, Google, and the web; an automated follow-up system running across all four locations simultaneously; a ScoreFlow model monitoring membership health and triggering reactivation before clients lapse; and a real-time InsightFlow dashboard delivering performance data to ownership every Monday morning without a single hour of management assembly. The 90-day build plan in Section 14 sequences this work to deliver measurable ROI within the first four weeks of implementation.

Primary Architectural Decisions

What This Architecture Enables

Once this system is live, every inbound inquiry from any channel receives a response within 60 seconds — not 5.5 hours. Every completed appointment triggers a post-visit sequence without a front desk staff member deciding to send it. Every member whose visit frequency drops below their personal baseline is flagged and contacted before the 30-day mark. Ownership reviews live performance data across all four locations at 7:00 AM every Monday without a single manager spending time assembling it. The 112 hours per week currently consumed by rule-based, repeatable work shift to client experience, upselling, and the high-touch work that automated systems cannot replace.

Audit Inputs Summary

Every system specified in this Architecture traces back to a finding in the April 2026 AI Operations Audit. This section documents the carried-forward findings and P1 automation opportunities that shape the build. The logic chain — Audit finding → Architecture response → Build deliverable — is explicit throughout this document.

Carried-Forward Audit Findings

P1 Automation Opportunities Carried Forward

Open Items From the Audit

Three items flagged in the Audit required resolution before Architecture could be finalized. All three were addressed in the Phase 02 kickoff session on May 5, 2026.

Client Systems Inventory

Imported and updated from the Phase 01 Audit (Section 02). Each tool is annotated with its architectural role — what it feeds into the system, what it receives, and the action required before or during the build. Action key: Keep + Connect — retained and integrated as-is. Keep + Reconfigure — retained with configuration changes. Replace — decommissioned and replaced by EnFlow OS or a new tool.

Workflow Redesigns

Each workflow is documented in its redesigned future state. The current state was established in the April 2026 Audit (Section 03). These redesigns are the specifications the Implementation team builds to. Every step marked "Automated" must have a named system, trigger, and action. Human steps are explicit about why judgment is retained.

Data Model

Enflow Systems maintains a single, normalized data model across all modules — HubSpot as the CRM layer, Vagaro as the booking and transaction system, and EnFlow OS as the behavioral and automation layer. All three systems operate on a shared view of six core entities: Account, Location, Contact, Appointment, Membership, and Interaction. Multi-tenant isolation is enforced at the database level through Account scoping on every query. Event sourcing captures every state change for audit compliance. Referential integrity is maintained through API-level constraints and webhook-driven consistency checks.

Global Entities

Operational Entities

Relationship Map & Cross-Module Dependencies

Contact → Appointment: One contact has many appointments (across locations). New appointment triggers AutoFlow pipeline entry and CampaignFlow sequence conditional on lead status.

Contact → Membership: One contact can hold zero or many memberships (multi-service, multi-location). Membership status feeds ScoreFlow health scoring. Payment failure on membership.payment_failed webhook triggers AutoFlow payment-recovery sequence.

Lead → Appointment: Lead progresses to Appointment when booked. HubSpot pipeline stage advances: "Qualified" → "Booked". No lead is converted to a contact until first appointment is confirmed.

WorkflowRun → ClientMessage: One workflow run produces many messages (SMS, email). Each message is a ClientMessage record linked to the WorkflowRun. Failed message triggers error escalation within the workflow.

Contact → ScoreFlowScore:One contact has one active ScoreFlowScore. Recomputed every 6 hours or on any appointment.completed event. Score changes trigger AutoFlow thresholds (e.g., health_score <60 → enter retention sequence).

Contact → AuditEvent: All Contact mutations — status changes, membership updates, data corrections — logged to AuditEvent. Audit trail is immutable and archived separately from operational data.

Multi-Tenant Isolation & Data Boundaries

Every table includes an account_id column. All queries filter by account_id at the application layer. Database-level row-level security (RLS) enforces account isolation — a query without account_id scoping returns no results. Cross-account data access is denied by default.

Location scoping: All user-level queries also filter by location_id (except Admin/Owner roles). A front desk user at Tampa sees only Tampa appointments, contacts, and lead assignments. Location managers see their location + read-only reporting on other locations.

Sensitive data segregation: PHI (medical history, contraindications) is stored only in JotForm Health, not in HubSpot or Vagaro. HubSpot and Vagaro contain only non-PHI fields (name, phone, service type, appointment timestamp). File records store only the storage URL and metadata; no medical data is embedded in the File object itself.

Event Sourcing & Audit Trail

Every state change is immutable. AuditEvent records capture: timestamp, user_id, action (create/update/delete), before_state (full JSON), and after_state (full JSON). This enables complete audit compliance, point-in-time data recovery, and dispute resolution.

Webhook events from Vagaro (appointment.completed, membership.payment_failed, etc.) are themselves audit events. They are logged, timestamped, and retained for 7 years minimum. Failed webhook deliveries are retried 3 times with exponential backoff; all retry attempts are logged.

Contact status changes (prospect → client → inactive) are tracked with reason and timestamp. If a contact is inactivated, their associated leads and workflows are flagged, not deleted.

EnFlow OS Module Alignment

Integration Map

Enflow Systems operates as a data orchestration layer, connecting Vagaro (system of record for appointments), HubSpot (operational CRM), and external channels (Instagram, Google, SMS, email) into a unified automation backbone. Six integration vectors carry data: Vagaro webhooks fire AutoFlow triggers; HubSpot contacts and properties feed scoring; communication channels route through Twilio and HubSpot email; InsightFlow pulls reporting data from all sources; and webhooks from external systems (payment failures, form submissions) drive event-driven logic. Every integration has explicit sync rules, retry logic, and fallback behavior.

Core Integrations

Data Flow Diagram (Textual)

Sync Rules & Reconciliation

Webhook Architecture & Security

Inbound webhooks from Vagaro, Twilio, JotForm, and Meta are received at a single gateway endpoint. Each webhook is authenticated via signed header verification (HMAC-SHA256). Webhook payloads are logged (without sensitive data) before processing. Processing is asynchronous — webhooks are immediately acknowledged (HTTP 200) and queued for processing.

Outbound webhooks to HubSpot, Twilio, and Slack are authenticated via API keys stored in EnFlow OS secrets manager. All outbound calls use TLS 1.3. Request timeouts set to 10 seconds; failed requests are queued for retry.

Webhook retry logic: Failed webhooks are retried up to 3 times with exponential backoff (5 seconds, 25 seconds, 125 seconds). After 3 failures, the event is logged to AuditEvent and flagged in the ops dashboard for manual investigation. No webhook is silently dropped.

Idempotency: All webhook handlers are idempotent. Receiving the same webhook twice produces the same result. This is enforced via idempotency keys (webhook ID + timestamp) stored in a short-lived cache. Duplicate webhooks within 1 minute are silently ignored.

API Gateway & Rate Limiting

All external API calls are routed through an API gateway layer. Rate limits are enforced per endpoint:

EnFlow OS Configuration

Enflow Systems plugs into EnFlow OS through a registration interface that exposes Enflow's entities (Contact, Appointment, Membership, ScoreFlowScore) as first-class objects within the OS. The OS sees Enflow Systems as a data provider and an action executor — the system ingests Enflow data for behavioral scoring and automation, and Enflow executes the resulting workflows (send SMS, update CRM, escalate to human). This section documents module registration, trigger/condition/action specs, and cross-module event propagation.

Module Registration & Manifest

Enflow Systems registers itself to EnFlow OS via a manifest file deployed at module initialization:

Trigger Registry & Emission Specs

Condition & Action Registry

Conditions are predicates evaluated within AutoFlow and CampaignFlow workflows. Conditions can reference Contact properties, Appointment data, ScoreFlowScore, or membership status.

Actions are executable operations invoked by workflows. Every action is atomic — it succeeds or fails completely. Failed actions trigger retry logic or escalation.

Cross-Module Event Propagation

Events flow bidirectionally between modules. No module is isolated.

Observability, Logging & Audit Integration

Enflow Systems inherits EnFlow OS logging and audit infrastructure. Every action, trigger, and state change is captured in the unified AuditEvent table. No local logs; all observability goes through EnFlow OS audit service.

Structured logging: Every log entry includes: timestamp, user_id (if human action), action_type, resource_id, before_state, after_state, metadata (JSON). Logs are immutable and retained for 7 years minimum (HIPAA compliance).

Observability dashboards: InsightFlow provides real-time visibility into workflow execution, message delivery rates, error counts by type, and latency percentiles. SLOs are defined:

Future Extensibility & Module Integration Points

Enflow Systems is designed for expansion into adjacent EnFlow OS modules without architectural changes.

AI Agents

Enflow Systems deploys four AI agents, each optimized for a specific domain within the customer lifecycle. All agents run on Claude 3.5 Sonnet with prompt caching enabled for cost efficiency and latency. Agents operate within strict guardrails — they can inform, suggest, and escalate, but cannot execute financial transactions, prescribe medical treatments, or access PHI data. Escalation to human staff is automatic when agent confidence falls below a threshold or when interaction falls outside trained domains.

Agent Catalog

Agent Memory & Retrieval Architecture

Intake Agent memory: Long-term memory stored in HubSpot Contact record (service history, preferences, location affinity, price sensitivity signals). Conversation context window: 10 messages or 15 minutes of active chat, whichever is longer. Memory is cleared between sessions unless client re-opens within 24 hours.

Scheduling Agent memory: Client availability patterns and historical rescheduling preferences (e.g., "always books afternoons on Thursdays"). Retrieved from Vagaro appointment history via vector similarity search on time slots. No persistent memory between conversations; data is always fresh from source systems.

Compliance Agent memory: No persistent memory. Stateless evaluation of each submission against hardcoded compliance rules (consent date validity, contraindication flagging, PHI field detection). Rules are versioned and deployed centrally; agents do not learn or evolve rules.

Insight Agent memory: Historical context retrieved from ClientMessage and Appointment tables. No learning across clients; insights are deterministic outputs of the conversation analysis pipeline, not ML-driven predictions.

Guardrails & Safety Boundaries

Agent Interaction Model & Workflow Integration

Agents operate within AutoFlow workflows as decision nodes. A message arrives → AutoFlow routes to appropriate agent → agent returns response + metadata (confidence, action flags, escalation status) → AutoFlow determines next step (send response, enroll in CampaignFlow, create task, escalate).

Intake Agent workflow: Inbound message → AutoFlow trigger → Intake Agent (response + lead qualification) → IF booking link clicked: advance HubSpot pipeline + enroll CampaignFlow → IF escalation flagged: create Slack alert + HubSpot task.

Insight Agent integration with ScoreFlow: On every appointment.completed, Insight Agent analyzes the client's full message history and appointment pattern. If upsell moment detected (e.g., client previously inquired about add-on services), recommendation is logged to InsightFlow dashboard for staff visibility. If churn signal detected (long message gaps, cancellation pattern), churn flag is sent to ScoreFlow for health score adjustment.

Observability & Audit Requirements

Every agent interaction is logged to AuditEvent with: agent_id, contact_id, conversation_id, input_message, output_response, confidence_score, guardrail_triggers (if any), escalation_status, timestamp. No agent output leaves the system without an audit trail.

Agent metrics are published to InsightFlow: response latency (p50/p95), confidence score distribution, escalation rate by reason, message classification accuracy (for intake agent qualification). SLO for agent response time: p95 <5 seconds.

Pipelines

Enflow Systems operates four pipeline categories: Event pipelines (webhook → trigger → action), Data pipelines (periodic Vagaro, HubSpot, Meta API pulls), Scoring pipelines (ScoreFlow health score calculations), and Sync pipelines (bidirectional Contact/Appointment sync). Each pipeline is versioned, observable, and implements explicit retry and dead-letter queue logic. Pipeline execution is idempotent — the same event processed twice produces the same result.

Pipeline Types & Execution Model

Retry, Backoff & Dead-Letter Queue Strategy

Event pipelines (sync execution): If processing fails, immediate retry (max 3 times) with exponential backoff: 1 sec, 5 sec, 25 sec. After 3 failures, event is moved to DLQ and logged to AuditEvent. DLQ events are reviewed manually within 24 hours. High-priority events (appointment.completed, payment failures) trigger a Slack alert when DLQ'd.

Data pipelines (async, batch): If a data pull fails (API error, timeout), the batch is marked failed and the next scheduled pull is triggered immediately. Failed pulls do not block subsequent pulls. Reconciliation jobs detect missing data from failed pulls and flag discrepancies.

Scoring pipelines:If score calculation fails for a single contact, the contact is flagged and the score recalc is deferred to the next batch. The Contact record is not left in an inconsistent state. A daily audit checks for stale scores (not updated in >24 hours) and triggers manual review.

Sync pipelines:If a sync fails (conflict detected, target API unavailable), the record is logged with before/after state and moved to a conflict queue. Conflicts are resolved in order of priority (payment_failed > appointment > contact) and retried every 5 minutes up to 288 times (24 hours).

Pipeline Versioning & Rollback

Every pipeline has a version identifier. Pipeline deployments are atomic — the old version runs until all in-flight requests complete, then the new version takes over. Rollback is automatic if new version error rate exceeds 5% within the first 10 minutes.

Breaking changes to pipeline data formats are prohibited. Data schema changes are additive only (new fields with defaults). Legacy field removal requires a 2-sprint deprecation notice.

Pipeline versions are logged in AuditEvent: pipeline_version_changed, old_version, new_version, deployment_timestamp, deployed_by_user_id.

Pipeline Observability & Monitoring

Automation Specifications

Enflow Systems implements a explicit trigger → condition → action execution model. Every workflow is deterministic and auditable. Actions are idempotent — running the same action twice produces the same result. Long-running workflows (multi-touch sequences) maintain state in the database. Human escalation is automatic when conditions cannot be resolved by logic.

Trigger → Condition → Action Execution Lifecycle

Idempotency & Deduplication

Every action includes an idempotency key: workflow_run_id + node_index + attempt_number. If the same action is executed twice (webhook retry, manual retry), the second execution is detected and skipped. The first result is returned instead.

Idempotency keys are stored in a cache with 24-hour TTL. After 24 hours, the key expires and the action is re-executable (acceptable for non-critical operations; critical operations enforce longer TTLs or manual approval).

Escalation Logic & Human-in-the-Loop Checkpoints

Long-Running Workflow State Management

Workflows that span multiple days (CampaignFlow sequences, retention sequences) are stored as WorkflowRun records with explicit state. Each day, a batch job checks for pending WorkflowRun.next_action_scheduled_at values and fires the next step.

State transitions are atomic: check current state → validate preconditions → update state → emit trigger. No partial state updates. If an error occurs during state update, the entire transaction rolls back.

Workflow state snapshots are captured at every transition and stored in AuditEvent for complete historical audit trail. This enables manual workflow recovery and debugging.

Dashboards & Reporting

InsightFlow provides four primary dashboards: Executive (ownership view of all 4 locations), Operations (location-level performance and anomalies), Agent (AI agent execution metrics and guardrail triggers), and Compliance (audit logs, data access, escalations). All dashboards update every 15 minutes. Custom reporting is available via the InsightFlow API for building ad-hoc queries.

Dashboard Catalog

Custom Reporting & Widget Framework

InsightFlow exposes a REST API for ad-hoc queries. All data is queried through this API — no direct database access. Query timeouts: 30 seconds max. Large queries (>1M rows) must be scheduled as background jobs.

Widgets are reusable dashboard components (line chart, bar chart, KPI card, table) with configurable data source (GROQ query or predefined metric). Widgets refresh independently: some every 5 minutes (operations), others every 1 hour (compliance audit). Widget caching reduces API load and improves dashboard responsiveness.

Dashboard permissions are role-based: Admin sees all data; Location Manager sees their location only; Esthetician sees no dashboards; Reviewer (InsightFlow-only role) sees Compliance & Executive dashboards only.

Compliance & Security

Enflow Systems is designed for HIPAA and SOC2 alignment. All data is encrypted in transit (TLS 1.3) and at rest (AES-256). Access control is role-based with explicit least-privilege scoping. Audit logs are immutable and retained for 7 years. Incident response procedures are documented and tested quarterly.

Data Classification & Protection

Access Control Model

All user authentication is SSO (SAML 2.0 or OIDC). No passwords. Password reset is not applicable. User accounts are deactivated (never deleted) on staff departure.

Role-based access control (RBAC) enforces permissions:

Data Retention & Deletion

Operational data (Contact, Appointment, Membership): Retained indefinitely unless client requests deletion (CCPA "right to be forgotten"). Deletion is a logical soft delete (marked deleted, not removed from database). Audit trail of the deletion is preserved.

PHI (JotForm): Retained for 7 years post-service delivery to comply with medical record retention laws. After 7 years, automatically deleted from JotForm. Retention date is calculated from last appointment date.

Audit logs (AuditEvent): Immutable and retained for 7 years minimum. Archive to cold storage after 2 years (still searchable, slower retrieval).

SMS consent: Maintained indefinitely. TCPA opt-out is honored immediately — any SMS to an opt-out contact is rejected at send time with a compliance error logged.

Incident Response Plan

Detection: Automated alerts fire on: unauthorized data access (AuditEvent anomaly), DLQ queue depth exceeding threshold, multiple failed authentication attempts from one IP, unexpected data export (bulk contact queries).

Containment (0–30 min): On-call engineer confirms incident. If data breach suspected: disable affected user accounts immediately, revoke API keys, page compliance officer and legal.

Investigation (30 min – 24 hours): Query AuditEvent for full access history. Identify: what data accessed, by whom, when, from where. Determine if PHI was involved.

Notification (24–72 hours): If PHI breached: notify all affected clients within 72 hours per HIPAA Breach Notification Rule. Document all notifications in AuditEvent and retain for 6 years.

Recovery & Learning (1 week): Post-mortem meeting. Identify root cause. Implement fix. Update incident response procedures if applicable.

Observability & SLOs

Enflow Systems emits metrics, logs, and traces to a centralized observability stack. All components report to a single InsightFlow instance. SLOs are defined for every subsystem with explicit error budgets. Alerting is threshold-based for predictable anomalies and anomaly-based for unexpected behavior patterns.

Observability Stack

SLO Catalog & Error Budgets

SLOs define acceptable reliability for each service. Error budget is the complement: if SLO is 99%, error budget is 1% (allowable failures). Every incident consumes error budget. Error budget exhaustion triggers "change freeze" — no new deployments until budget refreshes (monthly).

Alerting Rules & Escalation

Deployment Architecture

Enflow Systems runs on a managed cloud platform (AWS or equivalent) across three environments: Development (for feature work), Staging (for integration testing), and Production (live tenant data). Deployments use blue-green strategy for zero-downtime updates. Infrastructure is defined as code (Terraform). Secrets are managed through a centralized vault (AWS Secrets Manager or HashiCorp Vault).

Environment Configuration

CI/CD Pipeline

Scaling Rules & Auto-Recovery

Horizontal scaling:CPU > 70% for 2 min → add 1 instance. CPU <40% for 5 min → remove 1 instance. Memory > 80% → page on-call (potential memory leak).

Auto-recovery: If a container crashes, Kubernetes automatically restarts it. If restart fails 3x within 5 min, container is marked unhealthy and removed from load balancer. Page on-call after 3 consecutive failures.

Database failover:Prod Postgres runs in HA mode (primary + replica). On primary failure, replica automatically promotes (RTO <1 min). Automated failback when primary recovers.

Secrets Management

All secrets (API keys, database passwords, encryption keys) are stored in a centralized vault, never in code or config. Secrets are injected at runtime into container environment variables. Secrets are rotated automatically: API keys every 90 days, database passwords every 180 days.

Access to secrets is logged in AuditEvent. Accessing a production secret requires on-call engineer approval (even for automation). Unapproved access attempts trigger a security alert.

Operational Playbooks

Operational playbooks are step-by-step procedures for common scenarios: onboarding new tenants, responding to incidents, migrating data, and recovering from failures. Every playbook is executable by on-call staff without engineering escalation, when possible.

Playbook Catalog

Extensibility & Future Modules

Enflow Systems is architected for expansion into adjacent capabilities without architectural refactoring. New agents, pipelines, and modules are registered through the EnFlow OS manifest, inherit the same observability/audit infrastructure, and integrate via standardized trigger/condition/action model. Future modules can extend the platform without touching core code.

Extensibility Model

New Agent Development: Agents inherit a base class (Agent interface) that enforces: input/output schema, confidence scoring, guardrail checks, escalation logic. New agent is registered in OS manifest. At runtime, agent receives context (Contact, Appointment, message history) and returns response + metadata. No changes to core AutoFlow required.

New Pipeline Development: Pipelines inherit a base class (Pipeline interface) that enforces: trigger definition, processing model (sync/async), retry logic, observability hooks. Pipeline emits metrics and logs automatically. Dead-letter queue handling is built-in.

New Module Development: Modules expose entities (Contact, Appointment, etc.) and register triggers/conditions/actions. Entity schemas are versioned. Cross-module communication is via triggers (publish-subscribe) — no direct API calls between modules.

Future Module Catalog (Roadmap)

Build Plan & Milestones

Phase 03 Implementation runs 12 weeks (3 sprints of 4 weeks each). Every sprint delivers measurable ROI. Sprint 1 focuses on foundational integrations and reporting (InsightFlow live Day 1). Sprint 2 adds automation and AI agents. Sprint 3 completes the full system. Risk mitigation and dependency management are explicit in the timeline.

Phase 03 Build Schedule

30 / 60 / 90 Day Breakdown

Day 30 (End of Sprint 1):InsightFlow live and ownership using daily. Vagaro ↔ HubSpot sync stable. $42K annual intake labor savings validated (response time <60 sec). Measurement: agent latency p95 <5 sec, HubSpot data freshness <2 min.

Day 60 (End of Sprint 2):Intake Agent fully operational across Instagram, Google, web. All appointments generating post-visit SMS automatically. ScoreFlow identifying at-risk members. Retention sequence live at one location (pilot, full rollout Week 10). Measurement: intake agent qualification accuracy > 85%, post-visit SMS delivery > 99%, at-risk member detection latency <1 hour.

Day 90 (End of Sprint 3 + Stabilization):All workflows automated across all four locations. Zero manual intake admin. Zero manual reporting assembly. ROI measured: $181K in annual labor cost savings realized ($42K intake + $38K retention + $61K churn prevention + $18K HubSpot utilization + $22K reporting). System stable for 7+ days with <1% error rate across all pipelines.

Resourcing Assumptions

Risk Matrix & Mitigation

Success Criteria & Go-Live Checklist

System readiness:

Organizational readiness:

Post-launch (Day 1–7):On-call engineer monitoring. Daily standups with Serene & Co. ownership. Any critical bugs patched within 4 hours. Success: zero customer-impacting incidents, >95% automation completion rate, ownership satisfied with reporting.