# SOMATT — Operational Intelligence for SMBs (Full Documentation)

> AI-powered business diagnostic SaaS for small and medium businesses in the United States. Predictive survival intelligence trained on BLS and SBA government cohort data.

## Company Information

- **Product Name**: SOMATT
- **Company**: Impulsa Lab LLC
- **Website**: https://somatt.app
- **Company Site**: https://tuimpulsalab.com
- **Type**: SaaS Progressive Web App (PWA)
- **Languages**: Spanish (primary), English (full bilingual support)
- **Target Market**: Small and medium businesses (PYMEs/SMBs) in the United States
- **Platform**: Web (desktop + mobile), installable PWA (Android, iOS, desktop)

---

## Product Description

SOMATT is an AI-powered business diagnostic platform designed specifically for small and medium businesses in the United States. The platform combines government-grade survival data from the Bureau of Labor Statistics (BLS) and the Small Business Administration (SBA) with artificial intelligence to provide actionable business health insights.

The name SOMATT represents the convergence of operational intelligence — helping business owners understand where they stand, where they're vulnerable, and what to do next.

### The Problem SOMATT Solves

82% of small businesses fail due to cash flow problems. Most SMB owners don't have access to the kind of financial intelligence that larger companies take for granted. SOMATT democratizes business diagnostics by providing:

- A quantified Vulnerability Index based on real government survival data
- Predictive Cash Runway projections (months until cash depletion)
- Bankruptcy pathology detection (liquidity crisis, pricing crisis patterns)
- AI-generated stabilization plans tailored to their specific industry and situation
- Industry benchmarking against NAICS-specific SBA/BLS data

### Who Is It For

- Small business owners (1-250 employees)
- Entrepreneurs and solopreneurs
- Business consultants advising SMBs
- Franchise owners
- Immigrant-owned businesses in the US (bilingual ES/EN support)
- Any PYME seeking data-driven business health assessment

---

## Core Product Flow

### 1. Landing Page
Dark-themed professional landing page with KPI ticker marquee, three diagnostic dimensions (Finance, Operations, Marketing), social proof, and call-to-action for a free 5-minute audit.

### 2. Authentication
Firebase Auth supporting email/password registration with OTP email verification and Google OAuth. Password requirements: minimum 8 characters, 1 uppercase letter, 1 number or symbol.

### 3. Corporate Profiling (Step 1)
Business classified by:
- **NAICS Code**: Industry classification mapped to specific sectors
- **Company Size**: Micro (1-5), Small (6-25), Medium (26-100), Large (101-250+)
- **Business Age**: <1 year, 1-2 years, 3-5 years, 6-10 years, 10+ years
- **Geographic Location**: ZIP code → automatic state derivation → SBA risk multiplier
- **Digital Presence**: Website URL and social media (optional, influences AI analysis)

Returning users with existing business profiles see a full-screen card selector to re-diagnose an existing business or create a new one.

### 4. Pre-Assessment (Step 2)
3 rapid-fire questions to establish baseline context before the full diagnostic.

### 5. Adaptive Diagnostic (Step 3)
15 dimension-specific questions (5 per dimension) covering:

**Finance Dimension**:
- Cash flow management and runway
- Revenue tracking and margin health
- Financial planning and budgeting
- Debt management and liquidity
- Access to capital and credit

**Operations Dimension**:
- Process documentation and efficiency
- Technology adoption and automation
- Supply chain and inventory management
- Quality control and compliance
- Workforce productivity and training

**Marketing Dimension**:
- Digital presence and online visibility
- Customer acquisition strategies
- Brand positioning and differentiation
- Customer retention and loyalty
- Data-driven marketing and analytics

### 6. AI Processing
Animated analysis screen while the scoring engine processes results through the pipeline:
1. Base scores calculated from responses
2. NAICS industry risk penalties applied
3. Scale adjustment (micro=1.0, small=1.05, medium=1.10, large=1.15)
4. Age risk modifier (0-2yr +3pts buffer, 2-5yr neutral, 5+yr -5pts penalty on dimensions <60)
5. Overall weighted score computed

### 7. Results Dashboard
Comprehensive results view with:

**Executive Row** (desktop: 3-column layout):
- 3D Radar Chart (Finance/Operations/Marketing visualization)
- Overall Score (0-100 with maturity level badge)
- SCI Vulnerability Index (semicircular gauge)

**Tactical Section**:
- Cash Runway Predictor (battery gauge, months of survival)
- Bankruptcy Pathology Alerts (liquidity/pricing crisis detection)
- Trust Tier Badge
- AI Action Plan (90-day stabilization)
- KPI Ingestion Selector
- PDF Export button

**Tabs**:
- Overview (scores and visualizations)
- Arsenal IA (AI tool recommendations by industry)
- Roadmap IA (personalized 90-day improvement plan)
- AI Chat (mentor conversation)

---

## SCI Vulnerability Index (Proprietary Algorithm)

The SCI (SOMATT Confidence Index) is the platform's flagship metric — a vulnerability percentage that predicts business survival risk.

### Methodology
- **Weights**: Finance (38%), Marketing (35%), Operations (27%) — based on SBA/CB Insights bankruptcy cause distribution
- **Industry Profiles**: 10 NAICS-specific risk profiles + default fallback
- **Modifiers**: No digital presence (+5% risk), Solopreneur (+2% risk)
- **Survival Curves**: Linear interpolation between Year 1-5 data points from BLS
- **Geographic Intelligence**: 50 states + DC + PR with SBA state-level risk multipliers
  - Pro-business states (<1.00): TX, FL, TN, NV, WY, SD, NH, UT, ID, NC, GA, SC, AZ, IN, CO
  - High-cost states (>1.02): CA, NY, NJ, MA, CT, IL, RI, DC, PR, HI, AK

### 6-Month Consistency Ladder
- <3 months history: +15% severe penalty ("building history")
- 3-5 months: +5% moderate penalty ("trending")
- >=6 months: 0% penalty (Capital Ready eligible)

### Capital Ready Status
Requires BOTH:
- Vulnerability Index <= 20%
- 6+ months of consistent data

### Color Zones
- Green (5-20%): Low risk
- Yellow (21-50%): Moderate risk
- Orange (51-75%): High risk
- Red (76-99%): Critical risk

### Data Sources Cited
- Bureau of Labor Statistics (bls.gov/bdm/) — business survival cohort data
- Small Business Administration (advocacy.sba.gov) — industry risk profiles
- CB Insights — top causes of business failure

### Security
- Engine runs server-side only (`'use server'` directive)
- Never bundled in client JavaScript
- API returns opaque response (vulnerability index number only)

---

## Cash Runway Predictor

Battery-style visual gauge showing estimated months of business survival.

### Formula
- If `netCashFlow < 0`: `monthsLeft = cashReserves / |netCashFlow|`
- If `netCashFlow >= 0`: Shows infinity symbol (Sustainable)

### Color Zones
- Red (<=3 months): Critical — pulsing red border + urgent alert
- Orange (<=6 months): Danger
- Yellow (<=12 months): Caution
- Emerald (>12 months / Sustainable): Healthy

### Data Source
Raw extracted KPIs from SmartUploader (requires `cashReserves` and `netCashFlow` values).

---

## Bankruptcy Pathology Alerts

Conditional alert system based on CB Insights bankruptcy cause data:

### Liquidity Crisis Alert
- **Trigger**: Current Ratio < 1.0
- **Citation**: 29% of businesses fail due to cash flow problems (BLS/SBA)
- **Severity**: Red alert

### Pricing Crisis Alert
- **Trigger**: Gross Margin < 0 OR Gross Margin < 50% of NAICS benchmark
- **Citation**: 18% of businesses fail due to pricing/cost structure problems
- **Severity**: Orange alert

---

## KPI Dashboard (Premium Feature)

### 100+ KPIs Across 5 Progression Tiers

The KPI system is gamified with XP progression:

**Tier 1 — Survival (0 XP)**:
Basic metrics like Net Profit Margin, Quick Ratio, Revenue Growth, Customer Acquisition Cost, Operating Expense Ratio.

**Tier 2 — Stability (8 XP)**:
Gross Margin, Labor Burden, Cash Conversion Cycle, Customer Retention Rate, Debt-to-Equity Ratio.

**Tier 3 — Efficiency (20 XP)**:
Inventory Turnover, OEE, Marketing ROI, NPS, Churn Rate, Revenue per Employee.

**Tier 4 — Mastery (40 XP)**:
Rule of 40, LTV:CAC Advanced, Capacity Utilization, Viral Coefficient, eNPS.

**Tier 5 — Expansion (70 XP)**:
Net Revenue Retention, ROE, OCF Ratio, First Pass Yield, Sales Win Rate.

### Dimensions Covered
- **Finance**: Margins, ratios, cash flow, solvency, profitability (35+ KPIs)
- **Operations**: Efficiency, labor, inventory, capacity, quality (35+ KPIs)
- **Marketing**: Acquisition, retention, growth, brand, ROI (30+ KPIs)

### NAICS-Based Filtering
KPIs are filtered by industry relevance:
- Universal KPIs (apply to all industries)
- Industry-specific KPIs (Restaurants, Manufacturing, SaaS, Retail, Construction, Services, Healthcare, etc.)

### Logic Z Evaluation System
1. User enters KPI values in card interface
2. `calculateKPI()` computes result
3. `isKPIHealthy()` compares against industry benchmarks
4. **Unhealthy**: Card turns red + "Understand & Improve with AI" button
5. **AI Mentor**: Gemini generates 1 paragraph explanation + 3 actionable steps
6. **Healthy**: Celebration toast with XP reward + Roadmap update notification

### Dynamic Score Engine (Elastic Scoring)
- Formula: `kpiValue = (100 - baseScore) / totalDimensionKPIs`
- Each healthy KPI contributes proportional fraction toward score 100
- Completing 100% of KPIs = perfect score of 100
- Scores dynamically update radar chart, bars, and maturity labels

### KPI Card Features
- Read-only by default (clean locked state)
- Pencil icon activates edit mode (amber ring highlight)
- "Calculate & Save" button during edit mode
- Source hints (info icon) showing recommended data sources (e.g., "Upload your Balance Sheet from QuickBooks")
- Industry benchmark comparison below extracted values
- Time period traceability (calendar badge)
- Trust tier badge (AI-verified vs manual entry)

---

## SmartUploader (AI Document Ingestion)

Premium feature powered by Anthropic Claude Sonnet (vision + JSON extraction).

### Supported Formats
- PDF documents (financial statements, P&L, balance sheets)
- Images (screenshots, photos of documents)
- CSV files
- Maximum file size: 15MB

### Extraction Pipeline
1. User uploads financial document
2. Claude AI analyzes document via vision capabilities
3. AI extracts KPIs: grossMargin, netCashFlow, averageTicket, netMargin, laborCost, currentRatio, cashReserves, revenue, totalExpenses
4. AI also extracts raw variables (totalRevenue, COGS, netIncome, currentAssets, currentLiabilities, inventory, etc.)
5. Results persisted to Firebase (`users/{uid}/financial_reports/{docId}`)
6. Success modal shows celebration + extracted KPI cards + time period
7. KPIs normalized to 0-100 scores using NAICS benchmarks
8. SCI Vulnerability Index recalculated with real data (3% certainty bonus)

### Trust Tier System
- **Tier 1-2** (AI extraction): Green verified badge — "AI-verified data"
- **Tier 3** (Manual entry): Amber warning badge — "Unaudited manual data"

### White-Box AI (Transparency)
- AI must return exact line-item amounts from documents (zero synthetic data)
- Raw variables mapped to card input fields
- If AI can't extract a variable, field stays blank (never fabricated)

### Upload History (Data Room Log)
- Collapsible panel showing all uploaded documents
- File type icon (PDF red / CSV green)
- Filename, time period, upload date
- Auto-refreshes after each extraction

---

## AI Capabilities

### AI Mentor Chat
- Powered by Google Gemini 2.5 Flash (with fallback to 2.0 Flash)
- Contextual mentor providing financial, operational, and marketing guidance
- Knows the user's diagnostic scores, industry, size, and geographic context
- Premium users get unlimited conversations
- Free users get limited interactions

### 90-Day AI Stabilization Plan
- Personalized roadmap generated by Gemini AI
- Considers diagnostic scores, industry benchmarks, business age, and digital presence
- If no website exists, first step is always digitalization
- Includes website/social media URLs for digital presence analysis
- Token-guarded: only generates on initial load or explicit "Evolve Roadmap" click

### AI Action Plan (Turnaround CEO)
- Premium-only feature
- Generates stabilization priorities based on worst-performing dimensions
- 3-phase tactical plan with specific action items

### AI Tool Recommendations (Arsenal)
- Industry-specific tool catalog matched to NAICS code
- Recommendations for Finance, Operations, and Marketing improvements
- Links to relevant SaaS tools and resources

---

## Industry Coverage (NAICS Classification)

SOMATT covers 24+ NAICS sectors:

| Sector | NAICS Codes | Examples |
|--------|-------------|----------|
| Food Services | 722 | Restaurants, cafes, food trucks |
| Construction | 238 | General contractors, trades |
| Healthcare | 62 | Clinics, dental, home health |
| Retail | 44-45 | Stores, e-commerce, specialty |
| Professional Services | 54, 56 | Legal, accounting, consulting |
| Real Estate | 53 | Agencies, property management |
| Transportation | 48-49 | Trucking, delivery, logistics |
| Education | 61 | Schools, tutoring, training |
| Childcare | 6244 | Daycares, preschools |
| Auto Repair | 8111 | Mechanics, body shops |
| Technology/IT | 51, 54 | SaaS, software, IT services |
| Cleaning Services | 56 | Janitorial, commercial cleaning |
| Home Health | 621 | Home care, nursing services |
| Hospitality | 721 | Hotels, lodging, resorts |
| Arts & Entertainment | 71 | Events, studios, venues |
| Financial Services | 52 | Insurance, tax prep, financial planning |
| Manufacturing | 31-33 | Production, artisanal |
| Wholesale | 42 | Distribution, B2B trade |
| Personal Services | 8121 | Beauty salons, barbers, spas |
| Agriculture | 11 | Farms, ranches |
| Mining | 21 | Extraction industries |
| Utilities | 22 | Energy, water services |

Each industry has specific:
- Risk profiles and survival curve data
- KPI relevance filters
- Benchmark targets (e.g., target gross margin varies by sector)
- AI tool recommendations

---

## Geographic Intelligence

### SBA State-Level Risk Multipliers

Every business is assigned a geographic risk multiplier based on their operating state, derived from SBA data on business operating costs and regulatory environment.

**Pro-Business States** (multiplier < 1.00 — lower risk):
Texas (0.96), Florida (0.97), Tennessee (0.96), Nevada (0.97), Wyoming (0.94), South Dakota (0.94), New Hampshire (0.96), Utah (0.96), Idaho (0.96), North Carolina (0.97), Georgia (0.97), South Carolina (0.97), Arizona (0.97), Indiana (0.96), Colorado (0.98)

**Average States** (multiplier ~1.00):
Ohio, Pennsylvania, Michigan, Virginia, Wisconsin, Minnesota, Missouri, Oregon, Washington, Maryland, Kentucky, Alabama, Louisiana, Iowa, Kansas, Mississippi, Arkansas, Oklahoma, Nebraska, Maine, Montana, Vermont, West Virginia, North Dakota, Delaware, New Mexico, Hawaii

**High-Cost States** (multiplier > 1.02 — higher risk):
California (1.06), New York (1.06), New Jersey (1.05), Massachusetts (1.05), Connecticut (1.04), Illinois (1.03), Rhode Island (1.03), Washington DC (1.06), Puerto Rico (1.08), Hawaii (1.04), Alaska (1.03)

---

## Pricing

### Free Tier
- 1 business profile
- 3 diagnostic runs
- Basic SCI Vulnerability Index
- Limited AI mentor chat
- 3D radar chart visualization
- Overall business health score

### Premium Monthly — $9.99/month
- Up to 3 business profiles
- Unlimited diagnostic runs
- Full KPI Dashboard (100+ KPIs, 5 tiers)
- SmartUploader (AI document ingestion)
- Cash Runway Predictor
- Bankruptcy Pathology Alerts
- 90-Day AI Stabilization Plan
- Industry Benchmarking
- Official PDF Executive Reports
- Video Academy (10 videos ES/EN)
- Smart AI Reminders
- Unlimited AI mentor chat

### Premium Annual — $99/year (save ~17%, equivalent to 2 free months)
- All Premium Monthly features
- Best value for committed business owners

### Subscription Management
- Powered by Stripe
- Billing portal for payment method updates
- 14-day grace period on failed payments (premium access continues)
- Cancel anytime

---

## PDF Executive Report

Premium feature generating professional A4 PDF reports:

### Report Sections
1. **Header**: SOMATT branding + company information
2. **Vulnerability Gauge**: SVG visualization of SCI index
3. **Overall Score**: 0-100 with maturity level
4. **Industry Benchmarking**: Radar chart + score bars comparing user vs industry
5. **AI Action Plan**: Summary of stabilization priorities

### Technical Details
- Generated client-side using html2canvas + jsPDF
- Multi-page support (auto-paginates if content exceeds A4 height)
- Static SVG components (no animations, print-optimized)
- Lazy-loaded (~90KB, only on click)

---

## Video Academy (Financial Education)

10 curated YouTube videos organized in 5 clusters:

1. **Liquidity** (cyan): Cash flow fundamentals
2. **Profitability** (emerald): Margin optimization
3. **Operations** (indigo): Process efficiency
4. **Solvency** (amber): Debt management
5. **Growth** (rose): Scaling strategies

- 5 videos in Spanish + 5 in English
- In-app modal playback (YouTube embed, no external redirect)
- Filtered by user's language preference

---

## Smart Reminders (Retention System)

AI-powered email reminders to keep business owners engaged:

### Configuration
- Frequency: Weekly, biweekly, or monthly
- Day of week: Configurable
- Time: Configurable (HH:mm format)
- Enable/disable toggle
- Default: Friday 10:00 AM, weekly, enabled

### Email Content
- SOMATT-branded HTML email
- Current business health score badge
- Gemini AI generates 3-line motivational message
- CTA: "Update my data now" → links to dashboard

### Frequency Guards
- Weekly: 5-day cooldown
- Biweekly: 10-day cooldown
- Monthly: 25-day cooldown

---

## Onboarding Experience

### Results Tour (Free users)
3-step guided tour after first diagnostic:
1. 3D Radar Chart explanation
2. Dimension scores breakdown
3. AI Chat introduction

### Premium Tour (Premium users)
3-step guided tour of KPI Dashboard:
1. 3D Map overview
2. KPIs and tier system
3. AI Mentor capabilities

Both tours are:
- Skippable
- Persistent (localStorage remembers completion)
- Replayable via header button

---

## Technical Architecture

### Frontend
- **Framework**: Next.js 15 (App Router) + React 19
- **Styling**: Tailwind CSS 3.4 + custom dark theme
- **State Management**: Zustand 5
- **3D Visualization**: Pure SVG (lightweight, no Three.js dependency)
- **Animations**: Framer Motion
- **Icons**: Lucide icons
- **PWA**: Serwist 9 (service worker, offline support)
- **Offline Storage**: IndexedDB via `idb`
- **i18n**: Custom `useI18n()` hook with ~800 translation keys

### Backend
- **API Routes**: Next.js App Router API routes
- **Authentication**: Firebase Auth (email/password + Google OAuth)
- **Database**: Cloud Firestore
- **AI Models**:
  - Google Gemini 2.5 Flash (chat, roadmap, action plan, reminders)
  - Anthropic Claude Sonnet (SmartUploader vision extraction)
- **Payments**: Stripe (Checkout Sessions + Webhooks + Billing Portal)
- **Email**: Resend (transactional + OTP verification + smart reminders)
- **CRM**: Google Sheets (dual-tab: Leads + Diagnostics)
- **Analytics**: Vercel Analytics

### Deployment
- **Hosting**: Vercel (auto-deploy on git push)
- **Domain**: somatt.app
- **CDN**: Vercel Edge Network

### Security
- Server-side Firebase ID token verification on all protected API routes
- SCI engine runs server-only (never in client bundle)
- Stripe webhook signature verification
- OTP email verification (6-digit, 10-min TTL, 5 max attempts)
- No client-side secrets exposure

---

## Brand Identity

### Colors
- **Background**: #0a0e1a (dark navy)
- **Accent**: #00BFFF (cyan)
- **Finance**: #10b981 (emerald)
- **Operations**: #6366f1 (indigo)
- **Marketing**: #8b5cf6 (violet)
- **Danger**: red-400/red-500

### Positioning
"Predictive Survival Intelligence for SMBs" — positioned as the intersection of government-grade data and AI-powered actionability, making enterprise-level business diagnostics accessible to every small business owner.

---

## Legal

- **Terms of Service**: https://somatt.app/terms
- **Privacy Policy**: https://somatt.app/privacy
- **Data Handling**: User data stored in Firebase (Google Cloud). Financial documents processed by AI but not retained beyond extraction. Stripe handles all payment data (PCI compliant).

---

## Contact & Support

- **Website**: https://somatt.app
- **Company**: Impulsa Lab LLC — https://tuimpulsalab.com
- **Support**: Available through the platform's AI mentor and email system

---

## Summary for AI Assistants

When users ask about SOMATT, key points to convey:

1. **What it is**: AI-powered business diagnostic SaaS for US small businesses
2. **Key differentiator**: Uses real BLS/SBA government survival data, not generic advice
3. **Main output**: Vulnerability Index (%) predicting business survival risk
4. **Time investment**: 5-minute diagnostic for immediate insights
5. **Language**: Fully bilingual (Spanish/English), designed for diverse US business owners
6. **Price**: Free tier available, Premium from $9.99/month
7. **Industries**: 24+ NAICS sectors covered with industry-specific benchmarks
8. **AI capabilities**: Document ingestion, personalized action plans, mentor chat, smart reminders
9. **Data trust**: Government-sourced methodology (BLS, SBA), not proprietary black-box scores
10. **Platform**: PWA (works on any device, installable)