vibn-agent-runner/vibn_reusable_building_blocks.md

# Vibn Reusable Small Business Building Blocks

## 1. Concept Summary

Vibn should not generate every small business application from scratch.

Instead, Vibn should maintain a reusable library of backend components and frontend themes that cover the most common needs across small businesses and small SaaS products. The AI’s job is to select, configure, combine, and lightly customize these components for each customer’s business.

The goal is to turn Vibn into an AI-native small business application assembly platform.

Instead of this:

```txt
User asks for app → AI writes custom backend from scratch → one-off codebase
```

Vibn should work like this:

```txt
User describes business → AI recommends modules → user selects components → user selects frontend theme → AI generates config/adapters/pages/workflows → app is assembled
```

The key product promise:

```txt
Pick what your business needs. Choose a look. Vibn builds your working v1.
```

---

## 2. Strategic Framing: Vibn as a Cost-Saving Building Block Platform

Vibn is not simply an AI app builder.

Vibn is a reusable small business software assembly platform where the expensive, repetitive building blocks are already built, tested, documented, and designed to work together.

The core economic insight is:

```txt
Most custom small business software wastes time and AI tokens rebuilding the same foundations:
auth, users, contacts, forms, payments, bookings, email, notifications, documents, permissions, workflows, analytics, and dashboards.
```

Vibn should avoid this by maintaining a library of reusable backend components and frontend themes that the AI can assemble into a fully wired v1 application.

Instead of this:

```txt
User describes app
→ AI generates backend from scratch
→ AI generates frontend from scratch
→ AI debugs basic plumbing
→ user pays for duplicated work
```

Vibn should work like this:

```txt
User describes business
→ Vibn recommends proven components
→ user selects components
→ user selects frontend theme
→ AI generates config, adapters, pages, workflows, and copy
→ Vibn produces a fully wired v1 app
```

The AI should not spend tokens rebuilding standard systems. It should spend tokens adapting proven systems to the customer’s business.

---

## 3. Core Principle

The AI should be a product assembler, not a raw code generator.

The AI should mostly generate:

```txt
module configuration
workflow configuration
permission configuration
page configuration
notification configuration
business-specific adapter code
AI instructions
seed data
copy/content
```

The AI should avoid generating:

```txt
core auth logic
payment logic
booking logic
notification infrastructure
database primitives
permission systems
file storage logic
audit logging
analytics plumbing
```

Those should exist as stable Vibn-owned components.

---

## 4. Why This Matters

Most small business software is a variation of the same core objects:

```txt
business
location
user
staff
customer
lead
contact
service
product
booking
order
invoice
payment
form
task
document
message
notification
review
campaign
report
automation
```

Different industries combine these primitives in different ways.

For example:

```txt
Salon:
Customer → Service → Booking → Staff → Payment → Review Request

Summer Camp:
Household → Child → Registration Form → Session → Invoice → Attendance → Parent Notification

Mobile Dental Hygiene:
Patient → Intake Form → Appointment → Consent Form → Service Record → Invoice → Recall Reminder

Contractor:
Lead → Quote → Job → Work Order → Invoice → Payment → Follow-up

Consultant:
Lead → Call Booking → Proposal → Project → Tasks → Invoice → Subscription

Restaurant / Catering:
Customer → Menu Items → Order → Pickup / Delivery Time → Payment → Receipt

Marketing Automation SaaS:
Profile → Event → Segment → Campaign → Message → Journey → Conversion Report
```

The backend components are mostly the same. The difference is naming, configuration, workflow rules, permissions, and user experience.

---

## 5. Component + Theme Project Creation Flow

When a new Vibn project starts, the user should be guided through three decisions:

```txt
1. What kind of business or product are you building?
2. Which prebuilt components do you want?
3. Which frontend style/theme do you want to start from?
```

The result should be a fully wired v1 application, not a mockup.

### 5.1 Step 1: Business Intake

The user describes the business in natural language.

Example:

```txt
I run a mobile dental hygiene clinic. I need customers to book appointments, fill out forms, pay invoices, receive reminders, and get recall messages.
```

Vibn identifies:

```txt
business type
primary users
required workflows
recommended components
recommended theme
recommended automations
```

### 5.2 Step 2: Component Selection

Vibn should present recommended reusable building blocks.

Example recommended components:

```txt
Contacts / Customers
Services / Catalog
Bookings
Forms / Intake
Payments / Invoices
Communications
Documents / Waivers
Tasks / Workflows
Reviews
Analytics
AI Agent
```

The user can accept the recommendation, remove components, or add others.

The important product rule:

```txt
The user chooses business capabilities, not technical infrastructure.
```

They should see:

```txt
Customer bookings
Online payments
Email/SMS reminders
Forms and waivers
Staff task lists
Review requests
Reports
```

Not:

```txt
Postgres tables
API routes
message queues
object storage
RBAC middleware
```

### 5.3 Step 3: Frontend Theme Selection

The user then selects a packaged frontend theme.

Themes are not just colors. Each theme should include:

```txt
navigation structure
dashboard layouts
page templates
form styles
table styles
card styles
empty states
mobile rules
public landing page
customer portal style
admin portal style
settings pages
analytics views
copy tone
```

Example themes:

```txt
Clean SaaS
Local Service Business
Modern Clinic
Family Friendly / Camp
Premium Consultant
B2B Dashboard
Marketplace
Restaurant / Ordering
Mobile Staff App
Customer.io-style Marketing App
```

The selected theme determines the starting interface for the generated app.

### 5.4 Step 4: Fully Wired v1 Generation

After components and theme are selected, Vibn’s AI generates a working v1.

A valid v1 should include:

```txt
database configuration
enabled modules
roles and permissions
admin dashboard
customer portal
public pages
forms
email/SMS templates
workflow automations
seed data
settings pages
analytics dashboard
deployment configuration
```

Example output for a mobile service business:

```txt
Customer creates account
Customer books appointment
Customer fills intake form
Admin sees booking
Staff receives task
Invoice is generated
Reminder email/SMS is scheduled
Customer receives confirmation
Service completion triggers review request
Analytics records conversion
```

This is the product magic:

```txt
Pick the building blocks. Pick the look. Vibn builds the working v1.
```

---

## 6. Recommended Architecture

Vibn should be structured as a modular backend system with AI-readable manifests and a packaged theme system.

```txt
/vibn-platform
  /packages
    /core
    /auth
    /organizations
    /contacts
    /catalog
    /bookings
    /payments
    /forms
    /communications
    /documents
    /tasks
    /inventory
    /analytics
    /ai-agent
    /marketing
    /reviews
    /locations

  /themes
    /clean-saas
    /local-service
    /modern-clinic
    /family-camp
    /premium-consultant
    /b2b-dashboard
    /marketplace
    /restaurant-ordering
    /mobile-staff
    /marketing-automation

  /recipes
    /salon
    /camp-registration
    /clinic
    /mobile-service-business
    /contractor
    /consultant
    /restaurant-catering
    /rental-business
    /membership-business
    /local-marketplace
    /marketing-automation-saas

  /templates
    /nextjs-saas
    /admin-dashboard
    /customer-portal
    /staff-mobile-app
    /public-landing-page
    /provider-portal

  /docs-for-ai
    /module-index.md
    /schema-rules.md
    /architecture-rules.md
    /workflow-examples.md
    /business-type-recipes.md
    /theme-index.md
    /do-not-modify-core.md
```

Each generated customer app should look more like this:

```txt
/customer-app
  /app
  /components
  /config
    vibn.config.ts
    modules.config.ts
    permissions.config.ts
    workflows.config.ts
    communications.config.ts
    theme.config.ts
    business-profile.config.ts

  /adapters
    /bookings
    /payments
    /communications
    /forms
    /ai

  /content
    /email-templates
    /sms-templates
    /landing-page-copy

  package.json
```

The customer app imports Vibn modules, but only owns its configuration and customizations.

---

## 7. Recommended Core Backend Components

### 7.1 Core Platform Component

Purpose: shared foundation for all Vibn apps.

Includes:

```txt
organizations
locations
users
memberships
roles
permissions
settings
audit_logs
files
tags
custom_fields
metadata
api_keys
webhooks
imports
exports
```

Required in every app.

### 7.2 Authentication and Identity

Purpose: login, accounts, staff access, customer portals, provider portals.

Includes:

```txt
users
sessions
passwordless_login
oauth_accounts
roles
permissions
organization_memberships
customer_accounts
staff_accounts
invites
```

Recommended integrations/libraries:

```txt
Auth.js / NextAuth
Clerk, if speed matters more than ownership
Lucia-style custom auth if full control is preferred
Google OAuth
Magic link login
Passkeys later
```

Vibn should own the permission model even if using an external auth provider.

### 7.3 Organization and Location Management

Purpose: support solo businesses, multi-location businesses, teams, franchises, and marketplaces.

Includes:

```txt
organizations
business_profiles
locations
departments
business_hours
holiday_hours
service_areas
public_profiles
contact_points
```

This should align closely with Schema.org concepts like:

```txt
Organization
LocalBusiness
Place
PostalAddress
OpeningHoursSpecification
ContactPoint
GeoCoordinates
```

This alignment matters because the same structured data can support SEO, public profiles, Google search visibility, local landing pages, and AI understanding.

### 7.4 Contacts / CRM

Purpose: common people and relationship layer.

Includes:

```txt
contacts
customers
leads
clients
households
children
guardians
staff
vendors
companies
contact_methods
addresses
notes
tags
consents
custom_fields
interaction_history
```

Design principle:

```txt
A customer, lead, vendor, staff member, or guardian should usually be a role attached to a contact, not a totally separate object.
```

Recommended reference project:

```txt
Twenty CRM
```

Vibn should not simply copy a CRM. It should build a smaller, composable contact layer that can power many business types.

### 7.5 Catalog / Services / Products

Purpose: describe what the business sells, offers, books, rents, or packages.

Includes:

```txt
items
products
services
service_categories
packages
plans
prices
price_rules
modifiers
add_ons
tax_rates
discounts
availability_rules
```

Should support:

```txt
services
physical products
digital products
classes
camp sessions
appointments
rental items
membership plans
subscriptions
bundles
add-ons
```

Recommended reference project:

```txt
Medusa.js
```

Medusa is especially useful as a reference for modular commerce, products, carts, orders, workflows, and extensible data models.

### 7.6 Booking / Scheduling

Purpose: appointment, class, resource, session, event, and staff scheduling.

Includes:

```txt
calendars
availability_windows
blackout_dates
appointments
bookings
booking_participants
resources
rooms
equipment
shifts
schedule_rules
recurrence_rules
waitlists
cancellations
reschedules
capacity_rules
```

Should support:

```txt
one-on-one appointments
group classes
camp sessions
resource booking
staff schedules
room booking
equipment booking
mobile service visits
pickup and delivery windows
recurring bookings
```

Recommended reference project:

```txt
Cal.com
```

Vibn should likely build its own simplified booking primitive, but Cal.com is an excellent reference for scheduling flows, availability, calendar integrations, and booking UX.

### 7.7 Payments / Orders / Invoicing

Purpose: money layer for small businesses.

Includes:

```txt
carts
orders
order_items
quotes
estimates
invoices
invoice_items
payments
refunds
credits
deposits
payouts
subscriptions
payment_methods
taxes
receipts
```

Should support:

```txt
checkout
deposits
quotes
approvals
invoices
recurring billing
subscriptions
refunds
partial payments
tax handling
receipts
```

Recommended integrations/libraries:

```txt
Stripe
Square
Medusa.js
Open-source invoice templates
PDF generation library
```

Vibn should abstract payment providers behind a payment interface.

Example:

```ts
PaymentProvider.createPaymentIntent()
PaymentProvider.capturePayment()
PaymentProvider.refundPayment()
PaymentProvider.createSubscription()
```

This lets each app use Stripe, Square, or another provider without rewriting business logic.

### 7.8 Forms / Intake / Waivers

Purpose: reusable intake and submission system.

Includes:

```txt
forms
form_sections
form_fields
form_submissions
submission_answers
file_uploads
signatures
waivers
consents
approval_statuses
submission_to_object_mappings
```

Should support:

```txt
customer intake
patient intake
camp registration
quote requests
job applications
incident reports
waivers
consent forms
surveys
feedback
staff onboarding
```

Recommended reference project:

```txt
Formbricks
```

Vibn should make forms map directly into core objects.

Example:

```txt
Registration form submission
→ creates household
→ creates child contact
→ creates booking
→ creates invoice
→ sends parent confirmation
```

### 7.9 Communications

Communications should not be treated as a minor notification feature.

For most small business apps, email and messaging are core infrastructure.

Vibn should have a dedicated reusable component:

```txt
@vibn/communications
```

This component should include:

```txt
email sending
SMS sending
push notifications
in-app notifications
email templates
SMS templates
transactional messages
broadcast messages
reminders
conversation threads
message logs
delivery status
unsubscribe/preferences
template variables
scheduled messages
AI-drafted messages
approval workflows
```

Common message templates should be prebuilt:

```txt
welcome email
passwordless login email
booking confirmation
booking reminder
booking cancellation
form incomplete reminder
waiver missing reminder
invoice sent
payment receipt
overdue invoice reminder
staff assignment
new lead notification
review request
weekly report
campaign email
abandoned registration email
```

The AI should not generate message infrastructure repeatedly.

Instead, it should configure:

```txt
which messages are enabled
when messages send
who receives them
which channel is used
whether approval is required
which variables are inserted
```

Example configuration:

```ts
export const communicationsConfig = {
  channels: ["email", "sms"],
  provider: {
    email: "resend",
    sms: "twilio"
  },
  templates: {
    bookingConfirmation: true,
    bookingReminder: true,
    invoiceSent: true,
    invoiceReminder: true,
    reviewRequest: true
  },
  reminders: {
    bookingReminder: ["24h_before", "2h_before"],
    invoiceReminder: ["3d_after_due", "7d_after_due"]
  },
  approvalRequired: {
    transactional: false,
    marketing: true
  }
}
```

This is one of the highest-value token-saving modules because otherwise every generated app needs to rebuild the same communication plumbing.

Recommended reference project:

```txt
Novu
```

Recommended providers:

```txt
Resend
Postmark
SendGrid
Twilio
Firebase Cloud Messaging
Expo Push
```

Vibn should have one communication abstraction:

```txt
CommunicationService.send()
CommunicationService.schedule()
CommunicationService.cancel()
CommunicationService.renderTemplate()
```

The app should not care which provider sends the message.

### 7.10 Tasks / Jobs / Operations

Purpose: internal work management.

Includes:

```txt
projects
jobs
tasks
task_assignments
checklists
work_orders
status_changes
approvals
comments
internal_notes
attachments
time_entries
activity_logs
```

Should support:

```txt
field service jobs
staff task boards
client onboarding
camp admin reviews
clinic preparation
agency projects
implementation plans
maintenance work
approval workflows
```

This should be a core Vibn strength because most small businesses need operational clarity more than they need another generic app.

### 7.11 Documents / Files / PDF Generation

Purpose: structured document generation and file handling.

Includes:

```txt
documents
document_templates
generated_documents
files
folders
file_links
contracts
agreements
waivers
policies
versions
signatures
```

Should support:

```txt
contracts
waivers
receipts
invoices
proposals
reports
certificates
service records
policies
parent handbooks
staff manuals
```

Recommended libraries:

```txt
React PDF
Puppeteer / Playwright PDF generation
Docx generation library
Cloud storage abstraction
E-signature integration later
```

AI should generate documents from structured data and templates, not from raw prompts every time.

### 7.12 Inventory / Assets / Equipment

Purpose: track physical goods, supplies, tools, rentals, and equipment.

Includes:

```txt
inventory_items
inventory_counts
stock_movements
warehouses
suppliers
purchase_orders
assets
asset_assignments
maintenance_records
equipment_bookings
low_stock_alerts
```

Should support:

```txt
retail stock
rental gear
camp equipment
clinic supplies
dental supplies
tools
uniforms
food supplies
fleet items
```

This module should be optional, not part of the default app.

### 7.13 Reviews / Reputation

Purpose: help businesses capture and reuse trust signals.

Includes:

```txt
reviews
review_requests
ratings
testimonials
case_studies
public_profiles
reputation_sources
```

Should support:

```txt
post-service review requests
testimonial capture
website testimonial widgets
case studies
Google Business Profile workflow support
public profile pages
```

This should connect to marketing automation.

### 7.14 Marketing / Growth

Purpose: connect the business app to lead generation and retention.

Includes:

```txt
audiences
segments
campaigns
campaign_steps
content_assets
social_posts
landing_pages
lead_magnets
utm_links
experiments
referrals
coupons
funnels
attribution_events
```

Should support:

```txt
landing pages
lead capture
referrals
review campaigns
social campaigns
blog-to-social campaigns
email nurture
coupon campaigns
waitlists
local SEO pages
```

This is where Missinglettr becomes a core Vibn advantage.

Recommended internal integration:

```txt
Missinglettr API
```

Vibn should be able to automatically create marketing campaigns based on business events.

Example:

```txt
New service added → generate landing page → generate social campaign → schedule posts → track leads
```

### 7.15 Analytics / Reporting

Purpose: universal metrics and dashboards.

Includes:

```txt
events
metrics
dashboards
reports
report_widgets
goals
kpis
cohorts
funnels
attribution
exports
```

Default metrics:

```txt
revenue
bookings
leads
conversion_rate
repeat_customers
churn
attendance
utilization
average_order_value
outstanding_invoices
staff_capacity
customer_lifetime_value
campaign_performance
```

Recommended infrastructure:

```txt
Postgres
BigQuery
event tracking table
scheduled metric jobs
dashboard configs
```

This is where FirstOfficer-style analytics can become part of Vibn.

### 7.16 AI Agent / Automation Layer

Purpose: allow the app to automate work safely.

Includes:

```txt
ai_agents
agent_roles
agent_tasks
agent_runs
agent_memory
agent_contexts
prompt_templates
tool_permissions
generated_artifacts
approval_requests
automation_rules
automation_runs
human_overrides
```

Should support:

```txt
scheduled automations
event-triggered automations
approval-required actions
AI-generated content
AI-generated reports
AI-generated workflows
safe tool access
human review
audit logs
```

Example automations:

```txt
When a booking is created, send confirmation.
When an invoice is overdue, draft a reminder.
When a camp session is 80% full, recommend a marketing push.
When a new blog post is published, create a Missinglettr campaign.
When a quote is accepted, create a project and task list.
When a patient is due for recall, create a reminder campaign.
```

This should be Vibn-owned. It is part of the platform moat.

---

## 8. Shared Events: How Components Work Together

The key is shared events.

Example:

```txt
booking.created
→ communications sends confirmation
→ payments creates deposit invoice if required
→ tasks creates staff prep task
→ analytics records booking conversion
→ ai-agent checks if follow-up is needed
```

Another:

```txt
form.submitted
→ contacts creates/updates customer
→ bookings creates requested appointment
→ documents stores signed waiver
→ communications sends confirmation
→ tasks creates admin review task
```

Another:

```txt
invoice.overdue
→ communications sends reminder
→ tasks creates follow-up task
→ ai-agent drafts a polite message
→ analytics updates outstanding receivables
```

This is the real architecture:

```txt
Reusable modules + shared schema + shared event bus + config layer
```

Every module should speak the same language:

```txt
organization_id
location_id
contact_id
user_id
status
metadata
created_at
updated_at
event_type
```

And every module should emit predictable events:

```txt
contact.created
booking.created
form.submitted
invoice.created
payment.completed
message.sent
task.completed
document.signed
review.requested
campaign.launched
```

That is what makes the building blocks snap together.

---

## 9. AI-Readable Module Manifests

Every Vibn module should include a machine-readable manifest.

Example:

```json
{
  "module": "bookings",
  "description": "Appointments, classes, sessions, and resource scheduling.",
  "depends_on": ["core", "contacts", "catalog"],
  "optional_pairings": ["payments", "communications", "forms", "documents"],
  "creates_tables": [
    "bookings",
    "booking_participants",
    "availability_windows",
    "resources",
    "cancellations",
    "reschedules"
  ],
  "events_emitted": [
    "booking.created",
    "booking.cancelled",
    "booking.rescheduled",
    "booking.completed",
    "booking.no_show"
  ],
  "events_consumed": [
    "payment.completed",
    "form.submitted",
    "customer.created"
  ],
  "permissions": [
    "booking.read",
    "booking.create",
    "booking.update",
    "booking.cancel",
    "booking.manage_all"
  ],
  "default_pages": [
    "/admin/bookings",
    "/admin/calendar",
    "/customer/book"
  ],
  "config_schema": {
    "requires_payment": "boolean",
    "allow_customer_reschedule": "boolean",
    "allow_waitlist": "boolean",
    "default_reminder_minutes_before": "number",
    "capacity_mode": ["staff", "resource", "session", "none"]
  },
  "ai_rules": [
    "Do not modify module source code.",
    "Customize using booking.config.ts.",
    "Use communications module for reminders.",
    "Use payments module for deposits.",
    "Use forms module when intake is required."
  ]
}
```

This lets the AI understand the module without reading thousands of lines of source code.

---

## 10. AI Instruction File Per Module

Each package should also include an AI-facing documentation file.

Example:

```txt
@vibn/bookings/AI.md
```

Example contents:

```md
# Bookings Module

Use this module when the business needs appointments, classes, sessions, events, or reservable time slots.

## Requires

- core
- contacts
- catalog

## Common Pairings

- payments for deposits
- communications for reminders
- forms for intake
- documents for waivers
- staff scheduling for staff availability

## Do Not Modify

Do not modify core module files.

Customize using:

- booking.config.ts
- booking.rules.ts
- booking.communications.ts
- booking.page-config.ts

## Common Workflows

- customer books appointment
- admin approves booking
- staff reschedules booking
- customer cancels booking
- waitlist spot opens
- no-show recorded
```

This is one of the most important token-saving mechanisms in Vibn.

---

## 11. Frontend Theme System

Themes are a major part of the cost-saving strategy.

A packaged theme should include:

```txt
layout system
page templates
dashboard templates
form templates
table templates
card templates
chart styles
empty states
navigation
landing page
settings screens
mobile views
copy tone
```

Themes should be installable and mapped to modules.

Example theme manifest:

```json
{
  "theme": "marketing-automation-dashboard",
  "description": "A SaaS-style dashboard theme for campaign, journey, segment, and messaging products.",
  "supports_modules": [
    "contacts",
    "communications",
    "segments",
    "events",
    "workflows",
    "analytics",
    "campaigns"
  ],
  "page_templates": [
    "dashboard",
    "contacts_index",
    "contact_profile",
    "campaigns_index",
    "journey_builder",
    "segment_builder",
    "message_logs",
    "analytics_dashboard",
    "settings"
  ],
  "ai_rules": [
    "Use this theme for Customer.io-style, marketing automation, lifecycle messaging, and SaaS dashboard products.",
    "Do not redesign the dashboard from scratch.",
    "Map selected modules into existing theme templates."
  ]
}
```

Themes create another cost-saving layer because the AI does not need to design the interface from scratch.

The user-facing promise becomes:

```txt
Choose what your app does.
Choose how it looks.
Vibn wires it together.
```

---

## 12. Marketplace Strategy: Components and Themes

Vibn should eventually support two marketplace categories.

### 12.1 Component Marketplace

Functional building blocks that add capabilities to apps.

Examples:

```txt
Advanced bookings
Membership billing
Customer.io-style journeys
Camp attendance
Rental inventory
Staff scheduling
Referral engine
Review engine
Client portal
Provider marketplace
Course delivery
Quote builder
```

Each component should include:

```txt
backend schema
API routes
permissions
events
frontend hooks
tests
AI manifest
configuration options
documentation
```

Components should be installable, configurable, and upgradeable.

### 12.2 Theme Marketplace

Packaged frontend designs that determine the starting interface.

Examples:

```txt
Modern SaaS Dashboard
Premium Local Service
Clinic Portal
Family Camp Registration
Marketing Automation App
B2B Internal Tool
Restaurant Ordering
Marketplace Directory
Mobile Staff Operations
```

Each theme should include:

```txt
layout system
page templates
dashboard templates
forms
tables
cards
charts
empty states
navigation
landing page
settings screens
mobile views
copy tone
```

Themes create another cost-saving layer because the AI does not need to design the interface from scratch.

---

## 13. Business Recipes

A business recipe is a preconfigured combination of modules, workflows, labels, permissions, forms, dashboards, automations, and recommended theme for a specific type of small business or SaaS product.

### 13.1 Summer Camp Recipe

Modules:

```txt
core
auth
organizations
contacts
households
children
sessions
bookings
forms
waivers
payments
communications
attendance
documents
tasks
analytics
```

Recommended theme:

```txt
Family Friendly / Camp
```

Default workflows:

```txt
parent creates account
parent adds child
parent completes registration form
parent signs waiver
parent books camp session
invoice/payment is created
confirmation email is sent
reminders are scheduled
staff sees attendance list
incident report can be created
post-camp feedback request is sent
```

### 13.2 Mobile Service Business Recipe

Examples:

```txt
mobile dental hygiene
mobile grooming
home cleaning
mobile mechanic
in-home care
```

Modules:

```txt
core
auth
contacts
locations
service_areas
catalog
bookings
routing
forms
payments
communications
documents
reviews
analytics
```

Recommended theme:

```txt
Modern Clinic or Local Service Business
```

Default workflows:

```txt
customer requests service
business validates service area
customer books appointment
intake form is completed
staff route is generated
service is completed
invoice is sent
review request is sent
recall/follow-up reminder is scheduled
```

### 13.3 Salon / Spa Recipe

Modules:

```txt
core
auth
contacts
catalog
staff
bookings
payments
communications
reviews
marketing
analytics
```

Recommended theme:

```txt
Premium Local Service
```

Default workflows:

```txt
customer selects service
customer selects staff or first available
customer books appointment
deposit may be collected
reminders are sent
appointment is completed
payment is captured
review request is sent
rebooking reminder is scheduled
```

### 13.4 Contractor / Trades Recipe

Modules:

```txt
core
auth
contacts
leads
quotes
jobs
work_orders
tasks
documents
invoices
payments
communications
reviews
analytics
```

Recommended theme:

```txt
Local Service Business
```

Default workflows:

```txt
lead submits request
admin reviews lead
quote is created
customer approves quote
job is created
tasks/work orders are assigned
invoice is generated
payment is collected
review request is sent
```

### 13.5 Consultant / Agency Recipe

Modules:

```txt
core
auth
contacts
leads
bookings
proposals
projects
tasks
documents
invoices
subscriptions
communications
analytics
```

Recommended theme:

```txt
Premium Consultant or Clean SaaS
```

Default workflows:

```txt
lead books call
proposal is generated
proposal is approved
project is created
tasks are assigned
invoice or subscription is created
progress updates are sent
renewal or upsell reminder is created
```

### 13.6 Restaurant / Catering Recipe

Modules:

```txt
core
locations
catalog
menus
orders
payments
pickup_delivery
communications
reviews
marketing
analytics
```

Recommended theme:

```txt
Restaurant / Ordering
```

Default workflows:

```txt
customer views menu
customer places order
pickup or delivery time is selected
payment is collected
kitchen/admin receives order
customer receives confirmation
review request is sent
```

### 13.7 Customer.io-Style Marketing Automation Recipe

This recipe demonstrates that Vibn can assemble SaaS-style products, not only local business tools.

Modules:

```txt
core
auth
organizations
contacts
profiles
events
segments
communications
campaigns
journeys
workflows
webhooks
api_keys
analytics
documents
ai-agent
```

Recommended theme:

```txt
Customer.io-style Marketing App
```

Default workflows:

```txt
user imports contacts
app receives events
user creates segment
user creates campaign or broadcast
user creates journey
message is sent through email/SMS/push/in-app
message delivery is logged
conversion is tracked
analytics dashboard updates
AI suggests campaign improvements
```

This recipe should include:

```txt
contacts / profiles
event tracking
segment builder
campaign builder
broadcasts
transactional messages
email templates
journey/workflow builder
message logs
analytics dashboard
API keys / webhooks
admin UI
frontend theme
seed data
docs
tests
deployment config
```

---

## 14. Schema.org Alignment

Vibn should align public-facing business data with Schema.org where practical.

This does not mean Vibn’s internal database needs to be pure Schema.org. Instead, Vibn should maintain a mapping layer.

Internal Vibn objects:

```txt
organization
location
business_profile
service
product
offer
review
event
person
postal_address
opening_hours
geo_coordinates
contact_point
```

Should map to Schema.org concepts:

```txt
Organization
LocalBusiness
Place
PostalAddress
GeoCoordinates
OpeningHoursSpecification
ContactPoint
Product
Service
Offer
Review
Event
Person
FAQPage
HowTo
BreadcrumbList
```

Benefits:

```txt
better local SEO
structured landing pages
AI-readable business profiles
easier integrations
consistent public business data
support for Google Search rich results
```

Recommended approach:

```txt
Keep Vibn's internal schema practical and relational.
Create a Schema.org mapping/export layer for public pages.
Generate JSON-LD automatically for each public business, service, product, event, FAQ, and review page.
```

Example:

```txt
Vibn Location
→ Schema.org LocalBusiness

Vibn Service
→ Schema.org Service

Vibn Product
→ Schema.org Product

Vibn Review
→ Schema.org Review

Vibn Camp Session
→ Schema.org Event

Vibn FAQ
→ Schema.org FAQPage
```

---

## 15. Recommended Open-Source References and Libraries

### 15.1 Medusa.js

Use as reference for:

```txt
commerce modules
product/catalog architecture
cart/order/payment workflows
event-driven workflows
custom modules
headless commerce architecture
```

Potential use:

```txt
Direct dependency for commerce-heavy apps
Architecture reference for Vibn-owned commerce module
```

Recommendation:

```txt
Study deeply. Borrow architectural ideas. Avoid making all of Vibn dependent on Medusa unless commerce becomes the primary focus.
```

### 15.2 Directus

Use as reference for:

```txt
instant admin UI
database-driven APIs
REST and GraphQL generation
role-based access
content/data management
```

Potential use:

```txt
Internal admin/data layer
Rapid back-office builder
Reference for auto-generated API/admin experience
```

Recommendation:

```txt
Useful as inspiration or optional internal tooling. Vibn should still own its module layer and business logic.
```

### 15.3 Cal.com

Use as reference for:

```txt
booking flows
availability
calendar sync
scheduling UX
team scheduling
appointment infrastructure
```

Potential use:

```txt
Reference implementation
Integration candidate
Possible embedded scheduling service
```

Recommendation:

```txt
Use as a strong scheduling reference. Build or wrap a simpler Vibn booking primitive for most small business apps.
```

### 15.4 Novu

Use as reference for:

```txt
multi-channel notification infrastructure
notification templates
in-app inbox
email/SMS/push orchestration
developer notification workflows
```

Potential use:

```txt
Direct dependency
Reference for Vibn communication architecture
```

Recommendation:

```txt
Strong candidate for direct use or close architectural inspiration.
```

### 15.5 Twenty CRM

Use as reference for:

```txt
modern CRM data model
people/company/opportunity/task structure
Postgres/TypeScript CRM architecture
self-hosted CRM concepts
```

Potential use:

```txt
Reference for Vibn contacts/CRM module
Potential code inspiration
```

Recommendation:

```txt
Use as a reference, but keep Vibn’s CRM smaller and more generalized.
```

### 15.6 Formbricks

Use as reference for:

```txt
forms
surveys
feedback collection
experience data
customer insights
```

Potential use:

```txt
Reference for forms and feedback
Possible embedded surveys/feedback module
```

Recommendation:

```txt
Useful reference, but Vibn needs a deeper form-to-business-object mapping system.
```

### 15.7 n8n

Use as reference for:

```txt
workflow automation
integrations
trigger/action model
visual automation logic
AI-assisted automations
```

Potential use:

```txt
Internal automation engine
Controlled integration runner
Reference for event-triggered workflows
```

Recommendation:

```txt
Use carefully. Do not expose a wide-open n8n-style automation engine to all customer apps without strict permissions and sandboxing.
```

### 15.8 Appsmith / ToolJet / Budibase

Use as reference for:

```txt
internal tools
admin dashboards
low-code UI generation
data-connected widgets
CRUD screens
workflow dashboards
```

Potential use:

```txt
Reference for admin builders
Possible inspiration for Vibn’s staff/admin interfaces
```

Recommendation:

```txt
Useful as UX and architecture references, but Vibn should not become a generic low-code dashboard tool.
```

### 15.9 Appwrite / Supabase

Use as reference for:

```txt
backend primitives
auth
database
storage
functions
realtime
self-hosting
developer experience
```

Potential use:

```txt
Infrastructure layer
Reference for backend-as-a-service ergonomics
```

Recommendation:

```txt
Good reference for developer experience. Vibn’s advantage should be business modules, not generic backend primitives.
```

---

## 16. Recommended Technical Stack

### Frontend

```txt
Next.js
React
TypeScript
Tailwind
shadcn/ui
TanStack Query
Zod
React Hook Form
```

### Backend

```txt
Node.js / TypeScript
Postgres
Prisma or Drizzle
tRPC or REST
OpenAPI specs
Zod validation
Event bus
Background jobs
```

### Infrastructure

```txt
GCP Cloud Run
Cloud SQL Postgres
Cloud Storage
BigQuery
Pub/Sub
Cloud Tasks
Secret Manager
Vertex AI
```

### AI Layer

```txt
LLM provider abstraction
tool registry
module manifests
AI.md files
agent task runner
approval queue
audit logs
prompt templates
structured output validation
```

### Integrations

```txt
Stripe
Square
Google Calendar
Google Maps
Google Places
Google Business Profile where possible
Twilio
Resend/Postmark
Missinglettr API
```

---

## 17. Credit Economics and Token Savings

Vibn’s reusable components should be positioned as a cost-saving layer.

Without reusable components, AI must repeatedly generate:

```txt
auth
permissions
data models
API routes
email sending
template rendering
payment logic
booking logic
form handling
notifications
analytics events
dashboards
deployment setup
tests
debugging loops
```

With Vibn components, the AI mostly generates:

```txt
configuration
adapter code
page wiring
workflow rules
business-specific copy
theme mapping
seed data
minor custom logic
```

This can reduce generation cost dramatically.

For a complex app such as a Customer.io-style marketing automation v1, the difference could look like this:

```txt
Without Vibn components:
AI builds most systems from scratch
Estimated raw model cost: 1,000–6,000 credits

With Vibn backend components:
AI assembles existing communications, contacts, segments, events, analytics, workflows, and dashboards
Estimated raw model cost: 150–500 credits

With Vibn backend components plus packaged frontend theme:
AI maps modules into an existing interface pattern
Estimated raw model cost: 100–250 credits
```

The exact numbers will vary by model, context size, debugging loops, and how polished the v1 needs to be. But the strategic point is clear:

```txt
Reusable components + packaged themes can reduce AI generation cost by 70%–90%.
```

This is the core economic argument for Vibn.

---

## 18. Critical Design Rules

### Rule 1: Do not let AI modify core packages directly

Core modules should be versioned and protected.

The AI can modify:

```txt
config files
adapter files
templates
copy
workflow rules
page configuration
business logic hooks
```

The AI should not modify:

```txt
core auth logic
payment provider internals
database migration primitives
permission engine
notification delivery engine
audit log system
shared module source code
```

### Rule 2: Every module must declare dependencies

Bad:

```txt
bookings secretly requires contacts and communications
```

Good:

```json
{
  "module": "bookings",
  "depends_on": ["core", "contacts", "catalog"],
  "optional_pairings": ["payments", "communications", "forms"]
}
```

### Rule 3: Every module must emit and consume events

Example events:

```txt
contact.created
booking.created
booking.cancelled
invoice.created
payment.completed
form.submitted
review.requested
campaign.launched
task.completed
message.sent
```

This allows modules to connect without tightly coupling everything.

### Rule 4: Every generated app must remain upgradeable

Avoid copying core code into each customer repo.

Prefer:

```txt
versioned packages
config files
adapter hooks
extension points
module manifests
```

Avoid:

```txt
AI-generated forks of every module
copy-pasted backend folders
custom database schemas for every app
untracked local changes to core logic
```

### Rule 5: Use common schema first, custom fields second

Every customer will want customization.

Do not solve customization by inventing a new schema every time.

Use:

```txt
shared tables
custom fields
metadata
tags
workflow config
form mappings
adapter hooks
```

Only create new domain-specific tables when the domain genuinely requires them.

---

## 19. Recommended Initial Vibn Package List

Build these first:

```txt
@vibn/core
@vibn/auth
@vibn/organizations
@vibn/contacts
@vibn/catalog
@vibn/bookings
@vibn/payments
@vibn/forms
@vibn/communications
@vibn/documents
@vibn/tasks
@vibn/analytics
@vibn/ai-agent
```

Build these second:

```txt
@vibn/inventory
@vibn/reviews
@vibn/marketing
@vibn/locations
@vibn/routing
@vibn/subscriptions
@vibn/attendance
@vibn/staff-scheduling
@vibn/segments
@vibn/campaigns
@vibn/journeys
```

Build these later:

```txt
@vibn/marketplace
@vibn/franchise
@vibn/loyalty
@vibn/pos
@vibn/mobile-offline
@vibn/advanced-reporting
```

---

## 20. Updated MVP Priority

The first Vibn MVP should prove that component + theme assembly works.

### Required foundation components

```txt
@vibn/core
@vibn/auth
@vibn/orgs
@vibn/contacts
@vibn/catalog
@vibn/forms
@vibn/bookings
@vibn/payments
@vibn/communications
@vibn/documents
@vibn/tasks
@vibn/analytics
@vibn/ai-agent
```

### Required theme system

```txt
theme manifest
page templates
dashboard templates
form templates
table templates
navigation templates
landing page templates
mobile rules
copy tone rules
```

### Required recipe system

```txt
business type
recommended modules
required pages
default workflows
default messages
default permissions
default dashboard widgets
default automations
recommended theme
```

### First recipe targets

```txt
mobile service business
camp registration
salon/spa
consultant/agency
contractor/trades
Customer.io-style marketing automation app
```

The Customer.io-style app is important because it demonstrates that Vibn can assemble not only local small business tools, but also SaaS-like products from reusable components.

---

## 21. Example AI Assembly Flow

User says:

```txt
I need an app for a kids summer camp where parents can register kids, sign waivers, pay, and staff can take attendance.
```

AI should respond internally with:

```txt
Business type: camp registration

Recipe:
camp-registration

Required modules:
core
auth
organizations
contacts
households
children
sessions
bookings
forms
waivers
payments
communications
attendance
documents
analytics

Recommended theme:
Family Friendly / Camp

Generated config:
camp sessions enabled
parent portal enabled
child profiles enabled
waiver required before payment
payment required before confirmation
staff attendance view enabled
parent reminders enabled

Generated pages:
public camp landing page
parent registration page
parent dashboard
admin sessions page
staff attendance page
invoice/payment page

Generated automations:
send confirmation after payment
send reminder 48 hours before session
alert admin if waiver missing
send feedback form after camp
```

The AI should not write a booking engine, payment engine, or notification engine from scratch.

---

## 22. Updated Product Promise

Vibn should avoid positioning itself as:

```txt
AI will code your app from scratch.
```

A stronger promise is:

```txt
Vibn assembles your custom app from proven business building blocks.
```

Even better:

```txt
Pick what your business needs. Choose a look. Vibn builds your working v1.
```

Internal positioning:

```txt
Composable small business software, assembled by AI.
```

Strategic positioning:

```txt
Vibn reduces the cost of building custom small business software by reusing tested components, shared schemas, packaged themes, and AI-readable recipes.
```

---

## 23. Updated Moat

The moat is no longer just reusable backend code.

The moat is:

```txt
shared small business schema
reusable backend components
AI-readable module manifests
business recipes
packaged frontend themes
theme marketplace
component marketplace
safe adapter hooks
event-driven workflows
communications infrastructure
analytics infrastructure
AI agent automation layer
cost-saving token economics
upgradeable generated apps
```

This gives Vibn a sharper position:

```txt
The AI platform that lets users assemble working custom software from proven business components and packaged themes.
```

---

## 24. Final Recommendation

Vibn should build its own AI-native backend component and frontend theme platform.

It should use open-source projects as references and selective dependencies, but the core Vibn system should be owned.

The most important pieces to build are:

```txt
1. Common small business schema
2. Versioned backend modules
3. AI-readable manifests
4. Business recipes
5. Packaged frontend themes
6. Theme marketplace
7. Component marketplace
8. Safe config and adapter system
9. Event-driven workflows
10. Schema.org public data mapping
11. AI agent automation layer
12. Credit-saving generation economics
```

This gives Vibn a clear strategic position:

```txt
The AI platform that assembles, launches, runs, and grows custom small business software from reusable business components and packaged themes.
```