# KojiOps

> Operations platform for restaurants, food halls, ghost kitchens, and multi-operator hospitality businesses. Unifies POS data, financial operations, staff management, inventory, compliance, and AI-powered intelligence in a single multi-tenant system.

## What KojiOps Is

KojiOps is a B2B SaaS operations platform for the hospitality industry. It serves any restaurant business — from a single-location operator to a food hall running 15 different restaurant concepts under one roof, each with their own POS system, staff, menus, and financial agreements.

The core problem: restaurant operations are fragmented across dozens of systems — POS terminals, spreadsheets, payroll apps, inventory tools, compliance trackers, scheduling software. When you add multi-operator complexity (food halls, ghost kitchens, hotel F&B), every transaction needs to be split across operators, tips need fair distribution, shared costs need allocation, and compliance needs tracking per jurisdiction. KojiOps replaces all of that with one platform.

## Who It's For

- Single-location restaurants looking for unified operations
- Food halls with multiple restaurant operators sharing a location
- Ghost kitchens running multiple virtual brands
- Multi-concept restaurant groups (same owner, multiple concepts)
- Hotel food & beverage operations
- Any hospitality business needing operational clarity across operators, locations, or brands

## POS Integration

KojiOps connects to multiple point-of-sale systems and normalizes their data into a unified format:

- **Toast** — OAuth 2.0 integration, orders, employees, menu sync
- **Square** — OAuth 2.0 integration, orders, catalog, employees
- **Clover** — OAuth 2.0 integration, orders, inventory, employees
- **GoTab** — API key integration, orders and menu data

New POS integrations are added through a meta-generator: ~80 lines of configuration produces a complete adapter with webhook handling, data normalization, and HMAC signature validation. This enables 48-hour integration turnaround for new POS systems.

The order processing pipeline:
1. POS webhook arrives with raw order data
2. Unified webhook handler validates HMAC signature and routes to correct adapter
3. Adapter normalizes data into StandardizedOrder format (Zod-validated)
4. Order processing pipeline orchestrates downstream: revenue splits, tip distribution, event emission
5. Data flows to analytics, projections, and settlement batches

## Financial Operations

### Revenue Splits
Automatically splits every order's revenue among operators based on configurable agreements:
- Percentage-based splits per operator
- Item-level attribution (which operator's menu item was sold)
- Platform fee calculation
- Handles discounts, service charges, and taxes at item level
- Conservation validation ensures totals always balance
- Multi-operator orders with cross-operator item attribution

### Tip Distribution
Calculates fair tip allocation across staff:
- Multiple strategies: equal, weighted, by_operator, by_role
- Tip pooling with configurable pool rules
- Conservation validation (tips always sum to the penny)
- Cent-precision financial math with banker's rounding
- Staff self-service tip viewing via portal

### Profit & Loss (P&L)
Full P&L calculation with multiple layers:
- **Gross Profit**: Revenue minus COGS (cost of goods sold)
- **Net Profit**: Gross profit minus labor costs
- Per-operator profit breakdown
- Per-location profit breakdown
- Daily profit trend analysis
- Margin percentage calculations
- Complete P&L report generation

### Cost of Goods Sold (COGS)
Recipe-based ingredient costing:
- Links menu items → recipes → ingredients → inventory items
- Resolves current costs from inventory
- Portion multiplier support
- Batch COGS calculation across entire menu
- COGS variance reporting and trend analysis
- COGS alerts when costs exceed thresholds

### Pour Cost
Beverage program cost tracking:
- Beverage recipe definitions with pour amounts
- Bottle depletion rates per drink modifier
- Pour cost target setting and tracking
- Batch calculation across all beverage recipes
- Bar-specific inventory with bottle counts and par levels

### Labor Costs
Jurisdiction-aware labor cost calculation:
- Pairs clock_in/clock_out time events into shifts
- Break time deduction
- **Jurisdiction-specific overtime rules**: Federal FLSA weekly OT, California daily OT, double-time rules
- Config-driven labor rules per location
- Hourly rate application by position
- Labor cost as percentage of revenue

### Double-Entry Accounting
Full general ledger system:
- Chart of accounts with hierarchical account structure
- Journal entry creation with debit/credit lines
- Journal posting with MFA requirement for financial controls
- Journal voiding with MFA requirement
- Trial balance reports
- Accounting export in multiple formats (payroll, journal, payroll-journal)
- Integration with operational transactions (orders, settlements, expenses auto-journalize)

### Settlements & Payouts
Daily financial settlement processing:
- Settlement batch creation per location per day
- Revenue split records per operator per batch
- Tip pool aggregation and individual distributions
- Stripe Connect integration for automated operator payouts
- Connected account onboarding, account link generation
- Payout status tracking and capability verification
- Refund tracking per order

### Budgets & Variance
Fiscal planning and monitoring:
- Budget creation per company/location with fiscal year periods
- Budget line items mapped to chart of accounts
- Budget revision tracking with full audit trail
- Budget templates for reusable structures
- Variance alerts with configurable warning/critical thresholds
- Actual vs. budgeted comparison by period

### Cost Allocation
Shared cost distribution across locations:
- Rules-based allocation methods: by revenue, by square footage, by headcount, by electricity usage, custom percentages
- Automatic allocation execution on schedule
- Location metric snapshots for allocation basis
- Generated expense records with journal entry links
- Full allocation audit trail

### Recurring Expenses
Operational cost management:
- Scheduled recurring expenses (rent, utilities, insurance, subscriptions)
- Multiple frequencies (monthly, quarterly, annual)
- Automatic expense record generation on schedule
- Linked to chart of accounts for proper journalization
- Loan and lease tracking with amortization schedules
- Individual loan payment records with principal/interest split
- Utility account tracking per location

### Financial Controls
- Financial approval workflows with configurable thresholds
- MFA-gated operations for journal posting, voiding, API key management
- Approval statistics and threshold management
- Comp/void request workflow: staff submits, manager approves/denies
- Full audit trail on all financial operations

### Data Quality
- Ledger balance validation
- Daily balance validation
- POS-to-ledger reconciliation
- Transaction gap detection
- Stop-the-line events for critical data issues

## Staff & HR (HRIS)

### Staff Records
- Employee profiles with contact info, position, hire date, status
- POS employee ID mapping (syncs staff between KojiOps and POS systems)
- Staff portal for self-service: view profile, schedule, certifications, tips, earnings
- Workforce events tracking: hire, termination, promotion, transfer, etc.

### Scheduling
- Shift template creation by day-of-week, position, and zone
- Weekly schedule building with drag-and-drop
- Schedule copying from previous weeks
- Coverage analysis: which shifts are filled, which are open
- Availability preferences: staff set their preferred hours and blackout dates
- Time-off request management with approval workflow
- Blackout dates for company-wide scheduling restrictions
- Zone-based scheduling (assign staff to bar, kitchen, patio, etc.)

### Shift Swap Marketplace
Full shift trading system:
- Staff post shifts they want to swap
- Other staff can offer to take or trade shifts
- Shift swap pool: post a shift for anyone to claim
- Manager approval workflow for swaps and pool claims
- Shift swap board for staff to browse available swaps

### Time Tracking
- Clock in/out with GPS location capture
- Break start/end tracking
- Current clock status per staff member
- Integration with scheduled shifts for comparison
- Time events feed into timesheet aggregation

### Timesheets
- Configurable timesheet periods (weekly, biweekly)
- Automatic aggregation from time events into timesheet lines
- Regular hours and overtime hours calculation
- Submission → review → approval → lock workflow
- Approval history audit trail
- Overtime rules per location/jurisdiction

### Contractor & Guest Workers
- Contractor onboarding with temporary platform access
- Access period management (extend/revoke)
- Conversion path from contractor to permanent staff
- Shift marketplace where contractors browse and claim available shifts
- Clock in/out for claimed shifts with rating system

### Performance Management
- Performance notes per staff member
- Follow-up tracking with overdue alerts
- Performance summaries
- Shift feedback collection (post-shift surveys)
- Rating, sentiment, and category tracking on feedback
- Anonymous feedback option

### Earnings & Compensation
- Staff earnings estimator
- Position-based hourly rates and annual salaries
- Department and seniority level tracking
- Tip earnings visibility via staff portal

## Skills, Certifications & Training

### Skills System
- Skill definitions with categories and max levels
- Staff skill level tracking with assessor and certification dates
- Skill templates that can be promoted across the organization
- Skill gap analysis
- Skill progression criteria: required task completions, accuracy thresholds
- Skill progression events and AI-generated advancement recommendations

### Certifications
- Certification template definitions (food handler, alcohol server, etc.)
- Validity periods with days-before-expiry alerts
- Staff certification records with issuance and expiry dates
- Document upload and storage for certification proof
- OCR document processing: upload a photo of a certificate, AI extracts data
- Renewal request workflow: staff submits evidence, manager reviews and approves
- Background renewal jobs for automated reminders
- Compliance status dashboard: who's compliant, who's expiring, who's non-compliant
- Position-based certification requirements
- Manager compliance alerts with configurable thresholds

### Training
- Training module creation with categories and estimated duration
- Lesson authoring within modules (content, quizzes, video references)
- Staff enrollment in training modules
- Progress tracking per lesson with quiz scores
- Manager sign-off on training completion
- Overdue enrollment tracking
- Training statistics dashboard
- Linked to skills: completing training can advance skill levels

### Playbooks (Knowledge Base)
- Operational playbook authoring with multi-page structure
- Page types: text content, checklists, procedures
- Playbook lifecycle: draft → submit for review → publish → archive
- Page reordering within playbooks
- Staff feedback on playbooks (ratings, comments, helpfulness)
- Unresolved feedback tracking for content improvement
- Target role filtering (show different playbooks to different roles)
- Statistics on playbook usage and engagement

## Task Management

### Basic Tasks
- Task creation with title, description, priority, due date
- Assignment to staff members
- Task lifecycle: pending → in_progress → completed/cancelled
- Task templates for reusable task definitions
- Category-based organization
- Create tasks from templates

### Smart Tasking (Quantifiable Task Distribution)
Skill-gated, fairness-tracked task distribution for measurable work:
- **Quantifiable task templates**: Define countable work (polish 200 pieces of silverware, bus 30 tables, wash 500 dishes) with unit of measure and target rate per skill level
- **Daily targets**: Set how much of each task needs to be done each day per location
- **Auto-distribution**: System distributes tasks across available staff based on skill levels, historical performance, and rotation fairness
- **Skill gating**: Tasks require minimum skill levels; staff can't be assigned work they're not qualified for
- **Rotation fairness**: Track assignment history to ensure equitable distribution — no one person always gets the worst tasks
- **Progress tracking**: Staff report completed quantities; system tracks completion percentage
- **Reassignment**: Managers can reassign, split, or redistribute tasks mid-shift
- **No-show and early departure handling**: Auto-redistribute orphaned tasks when staff leave unexpectedly
- **Bypass skill gate**: Manager override to assign tasks above normal skill requirements
- **Task dependencies**: Define ordering constraints (mop AFTER sweep)
- **Assignment history**: Full audit trail of who did what, when, and how well
- **Manager overrides**: Override auto-distribution with documented reasons

### Escalations & Decisions
- Escalation creation when staff encounter issues they can't resolve
- Assignment to managers with acknowledgment tracking
- Resolution workflow with notes
- Async decision system: submit decision request, manager approves/rejects asynchronously
- Manager action checking: determine if an action requires escalation before proceeding

## Zones (Physical Space Management)

### Zone Hierarchy
- Hierarchical zone definitions per location: location → floor → area → station
- Zone types: dining, bar, kitchen, patio, storage, prep, office, etc.
- Parent-child zone relationships (bar section within main dining floor)
- Zone equipment tracking (which equipment is in which zone)

### Zone Operations
- Staff-to-zone assignment during shifts
- Zone coverage analysis: which zones are staffed, which are uncovered
- Equipment-to-zone assignment
- Children zone navigation
- Location-wide zone hierarchy view

## Inventory & Purchasing

### Inventory Management
- Inventory item master data with categories, units, par levels, reorder points
- Stock level tracking per location: on-hand, committed, available
- Stock movements: receive, consume, transfer, adjust — full transaction log
- Point-in-time inventory snapshots for reporting
- CSV import/export for bulk operations
- Download import template

### Bar Inventory
- Bar-specific bottle tracking with bottle sizes and par levels
- Bar modifiers with bottle depletion rates per drink
- Separate bar inventory counts from general inventory

### Recipes
- Recipe definitions with yield, yield unit, and category
- Ingredient lists linking to inventory items with quantities and units
- Cost-per-unit calculation based on current inventory costs
- Recipe-to-menu-item linking for COGS flow

### Menus
- Menu creation and management
- Menu item definitions with description, category, price, availability
- Modifier groups: define groups of options (Toppings, Sides, Cooking Temp)
- Individual modifiers within groups with price adjustments
- Menu item to modifier group associations
- 86'd item management: mark items as unavailable with history tracking and restore

### Vendors & Purchasing
- Vendor records with contact info and payment terms
- Purchase order creation with PO numbers, expected delivery dates
- PO line items linking to inventory items with quantities and unit prices
- Received quantity tracking against ordered quantities
- PO lifecycle management

### Products (Catalog)
- Product catalog for ingredients and beverages
- UPC and package size tracking
- Cost per unit
- Brand associations
- Vendor-product pricing per operator
- Product tagging for categorization

## Orders & Tabs

### Order Management
- Order records with order number, type (dine_in, takeout, delivery, catering), status, totals
- Order items with menu item link, quantity, unit price, modifiers
- Order payments with payment method, transaction ID, status
- Order discounts, taxes, tips, service charges — all as separate tracked entities
- Discount presets and charge presets for quick application
- Order event lifecycle tracking

### Tabs (Open Checks)
- Open tab creation per table/customer
- Add items to running tab
- Tab transfer between tables
- Tab merging (combine multiple tabs)
- Tab closing with payment application
- Tab-to-order affiliations

### Comp & Void Workflow
- Comp/void request submission with reason
- Manager approval/denial workflow
- Comp and void records with amounts and reasons
- Statistics and history for audit

## Bookings & Catering

- Booking creation with customer info, event type, date, headcount
- Booking lifecycle: inquiry → confirmed → in_progress → completed → cancelled
- State transition tracking with reason and audit trail
- Booking line items: menu selections, equipment rental, service charges
- Payment tracking: deposits, installments, final payment
- Calendar view by month
- Booking statistics and summary dashboard

## Communication & Notifications

### Announcements
- Create announcements targeted to specific locations, roles, or staff
- Priority levels and expiration dates
- Announcement templates with categories for reuse
- Template instantiation for quick announcement creation
- View and acknowledgment tracking per staff member
- Pre-shift announcements filtered by location and date
- Engagement analytics (views, acknowledgments)

### Shift Notes
- Closer-to-opener handoff notes per location per date
- Urgent note flagging
- Note promotion to full announcement
- Read tracking
- Date range querying for historical notes

### Push Notifications
- Browser push notification subscriptions
- Subscribe/unsubscribe management
- Test notification sending
- Notification preference management per user (email, push, SMS toggles by category)

### In-App Notifications
- Notification messages with title, body, priority, action URL
- Read/unread tracking

### Operational Captures
- Quick note capture for operational observations (photos, text, issues)
- Feed into intelligence layer for pattern detection

## Compliance & Regulatory Engine

### Law Sources & Documents
- Track regulatory sources: Department of Health, ABC, OSHA, local jurisdictions
- Law document storage with effective dates
- AI-generated summaries of regulatory documents
- Document URL and reference tracking

### Compliance Rules
- Extract actionable rules from law documents
- Rule codes, severity levels, required actions
- Rule categorization: food_safety, labor_compliance, financial_audit, fire_safety, accessibility

### Compliance Packs
- Curated bundles of compliance rules per industry and jurisdiction
- Pack assignment to companies
- Industry type and jurisdiction scoping

### Compliance Checkpoints
- Scheduled compliance verifications per company
- Checkpoint types: food_safety, labor_compliance, financial_audit
- Configurable frequency
- Checkpoint execution records with pass/fail results
- Evidence linking to checkpoint executions

### Compliance Evidence
- Tamper-proof evidence storage with SHA-256 document hashing
- Evidence types: photo, document, signature, temperature_log, inspection_report
- Retention period management
- Linked to checkpoints for audit trail

### Compliance Monitoring
- Company-level compliance status tracking
- Alert thresholds: configurable warning/critical days before deadline
- Notify specific roles when thresholds are breached
- Non-compliant staff reporting
- Compliance dashboard with aggregated status

### HACCP
- HACCP compliance tracking for food safety
- Temperature monitoring and logging
- Critical control point management

## AI & Intelligence Layer

### Toji (AI Assistant)
Conversational AI assistant integrated throughout the platform:
- Context-aware: knows the user's role, location, current page, and recent activity
- Role-specific capabilities: owner gets financial insights, manager gets operational guidance, staff gets task help
- Integrates with Knowledge Layer: references playbooks, training materials, zone information
- Quick action suggestions based on conversation context
- Chip tools: can query, create, and reference Smart Chips during conversation
- Disambiguation UI for ambiguous entity references
- Conversation persistence with turn counting and outcome tracking
- Token usage tracking and cost monitoring
- Multi-provider LLM backend: Anthropic Claude, OpenAI, Groq, Ollama, Together AI
- PII redaction in prompts
- Grounding enforcement to prevent hallucination

### Smart Chip System (Knowledge Graph)
Entity @mention system that creates a queryable knowledge graph:
- 15 entity types: operator, order, skill, staff, location, vendor, company, task, inventory_item, purchase_order, settlement, shift, certification, recipe, menu_item
- @mention syntax in any text field: @staff:john_doe, @vendor:sysco, @recipe:margherita
- Bidirectional backlinking: see all mentions of an entity across the system
- Forward link navigation: see what entities a document references
- Entity hover cards with summary data
- Graph traversal: find paths between entities, discover connected clusters
- Neighborhood statistics per entity
- Chip search across all types or filtered by type
- Chip type registry for extensibility

### Entity Embeddings (Semantic Search)
- Embed entities into vector space for similarity search
- Find semantically similar entities across types
- Batch embedding operations
- Embedding service health monitoring

### Claims & Facts System
Intelligence extraction and verification:
- **Claims**: AI-extracted data with confidence scores per field
  - Claim types cover operational, financial, and HR data
  - Field-level confidence scoring
  - Source tracking (which conversation, document, or observation produced the claim)
  - Status lifecycle: pending → verified → promoted/rejected
- **Facts**: Verified, immutable data promoted from claims
  - Facts have validity periods (validFrom/validUntil)
  - Timeline view of facts for an entity
  - Entity-scoped fact queries
- **Promotion policies**: Configurable auto-promotion rules
  - Minimum confidence thresholds per claim type
  - Field-specific threshold overrides
  - Auto-promote when confidence exceeds policy thresholds

### Memory System
Cross-session AI memory:
- Document chunks: raw text broken into indexed chunks with content hashing
- Claim supersession graph: tracks when newer claims update, extend, or contradict older ones
- Materialized is_latest state per supersession key
- Memory edges: semantic relationships between atomic claims
- Pattern edges: higher-level behavioral pattern relationships
- Memory chip projections: materialized agent-facing view of claims
- Toji contexts: per-user cross-session memory (current focus, recent entities, preferences)
- Session history overflow storage

### Intelligence Loops
Self-improving intelligence system:
- Event-to-insight loop: captures operational events, detects patterns, generates insights
- Pattern-to-task loop: detected patterns suggest automated task creation
- Chip sentiment loop: analyzes sentiment across chip mentions
- Intelligence cycle trigger: manually kick off full analysis
- Business insights with confidence scoring and category classification
- AI-generated workflow suggestions based on detected repetitive patterns
- Anomaly detection on sales, labor, and inventory data
- Demand forecasting

### Action Cards (AI Nudges)
Proactive intelligence delivery:
- AI-generated action cards with type, priority, urgency, and confidence scores
- Card lifecycle: active → actioned/dismissed/snoozed/expired
- Execute action directly from card
- Dismiss with reason tracking
- Snooze for later
- Correction feedback: mark a card as incorrect, system learns
- Correction rules: learned patterns from user feedback to improve future cards
- Card statistics and history
- Expiration-based cleanup

### Business Discovery
Guided business intelligence sessions:
- Discovery sessions per operator covering business model, cuisine types, peak hours
- Business goal setting linked to locations and operators
- Goal tracking with target values and status
- Business insights generated from discovery data

### D15 Intelligence
Advanced reasoning system:
- Attractor detection and explanation
- Location-state analysis
- Intervention recommendations

## Workflow Automation

### Workflow Builder
User-created automation rules:
- Trigger types: event (order.created, task.completed), time_event, threshold, schedule
- Condition evaluation with AND logic
- Action execution: create task, send notification, update record, trigger webhook
- Enable/disable toggle per workflow
- Manual execution for testing
- Execution logs with success/failure tracking
- Test mode for dry runs
- AI-suggested workflows based on detected patterns
- Suggestion dismissal tracking

### Built-In Workflows
- Opening workflow: morning checklist automation
- Closing workflow: end-of-day checklist
- Exception playbooks: predefined responses to common operational exceptions

## Analytics & Reporting

### Pre-Computed Aggregations
- Daily location stats: revenue, order count, average check size, total tips
- Daily operator stats: revenue, order count, item count per operator
- Daily top items: ranked by quantity sold and revenue per location
- Daily sales digests: gross/net sales, taxes, tips, order counts

### Real-Time Analytics
- Live metrics with 30-second polling
- Metrics dashboard with current KPIs
- Speed of service (FOH) metrics

### Advanced Analytics
- Anomaly detection on any metric
- Demand forecasting
- True cost visibility (full cost stack per item/operator)
- Menu engineering analysis for menu optimization

### Projections (Materialized Views)
Event-sourced materialized views:
- Daily sales projection: gross/net sales, transaction count, hourly breakdown
- Labor hours projection: total/regular/overtime hours, labor percentage
- Inventory levels projection: on-hand, committed, available, below-par flags
- Prime cost projection: labor cost + COGS, daily variance tracking
- Projection freshness tracking (fresh/stale/unavailable/computing)
- TTL-based caching with trigger-based invalidation

### Dashboards
- Inventory dashboard: stock levels, low stock alerts, movement trends
- Staff dashboard: coverage, certifications, performance
- Compliance dashboard: checkpoint status, upcoming deadlines, violations
- Operations dashboard: task completion, zone coverage, shift status
- Owner dashboard: daily digest, revenue trends, operator performance
- Intelligence dashboard: insights, patterns, recommendations

## Platform Architecture

### Multi-Tenancy
Hierarchical tenant model:
- Company (root tenant boundary) → Location (physical site) → Operator (restaurant concept) → Staff
- Every database query is scoped by companyId at minimum
- Application-layer scope enforcement via TenantScopedRepository
- PostgreSQL Row-Level Security (RLS) as defense-in-depth
- Cross-tenant access blocked with audit logging
- Prometheus metrics for tenant isolation violations

### Authentication & Authorization
- Better Auth with email/password and Google OAuth
- TOTP-based MFA with backup codes
- Session management: 30-day sessions, HTTP-only cookies
- Rate limiting: 10 requests/minute per endpoint
- Role-based access control: super_admin, company_admin, location_manager, operator, staff, trainer, lead
- Permission-based authorization (not just role strings)
- User invitation system with pre-assigned roles and email verification
- Multi-role support: users can have different roles at different scopes
- Admin impersonation for testing with full audit trail

### Configuration System
Hierarchical configuration management:
- Config resolution across levels: global → company → location → operator
- Config audit trail per key
- Config import/export
- Distributed locking for concurrent config updates
- Lock renewal and cleanup

### Webhooks (Outbound)
- Webhook subscription management per tenant
- Event type filtering
- HMAC signature signing for webhook security
- Delivery tracking with HTTP status codes
- Retry logic for failed deliveries
- Webhook testing endpoint
- Available event types registry

### API Keys
- Programmatic API access with scoped keys
- MFA-gated key creation and rotation
- Key rotation warnings for keys approaching expiry
- Key deletion with MFA

### Billing & Usage
- Subscription plans: Free, Pro, Enterprise
- Stripe-integrated subscription management (create, upgrade, downgrade, cancel)
- Usage metering: track row reads, row writes, storage per company
- Usage-based overage billing
- Invoice generation and tracking
- Entitlements: feature access control per plan
- Quota enforcement per subscription tier
- Proration for mid-cycle plan changes
- Credit ledger for promotional credits
- Usage alerts with configurable thresholds
- Dynamic pricing with versioned configurations and approval workflows

### Real-Time
- WebSocket server with room-based subscriptions (company, location, user)
- Session-cookie authentication (not URL params)
- Heartbeat/ping-pong for connection health
- Message queue for offline clients
- Event bridge: internal events → WebSocket rooms + webhook delivery
- Event types: sales updates, inventory alerts, shift events, exception escalations, labor overtime alerts

### Data Privacy
- GDPR data deletion request workflow with approval
- Retention policy management
- PII encryption service

### Observability
- SLO/SLI monitoring with historical tracking
- Error budget consumption tracking
- Alert state management to prevent duplicate notifications
- Prometheus-compatible metrics endpoint
- Metrics rollup aggregation (1m, 5m, 15m, 1h, 1d granularity)
- Data quality event tracking

### Document Processing
- OCR-powered document processing for certifications and invoices
- Job-based workflow: upload → OCR → extraction → human confirmation
- AI classification for document types
- Processing statistics

### Codebase Self-Repair (Internal)
- Autonomous fix system: detect, fix, and submit code changes
- Fix attempt logging with LLM provider tracking
- Human review queue: approve/reject AI-generated fixes
- Approved pattern library for few-shot learning
- Coding philosophy violation tracking
- Confidence metrics per fix category

## Event System

KojiOps uses an event-sourced architecture for cross-domain communication:
- Canonical events persisted with aggregate type, version, and timestamp
- Entity event emitter with tenant scope and correlation ID tracking
- Event-to-workflow bridge for automation triggers
- Event ingestion service for external event sources
- Events feed projections, analytics, intelligence loops, and webhook delivery

## Pricing

- **Free**: $0/month — 100 MB storage, 10K row reads/month, 1K row writes/month, community support
- **Pro**: $49/month — 10 GB storage, 1M row reads/month, 100K row writes/month, priority support, advanced analytics
- **Enterprise**: Contact sales — unlimited storage, unlimited operations, dedicated support, custom integrations, SLA guarantees

Overage pricing: Storage $0.023/GB-month, Row reads $0.35/million, Row writes $1.00/million

## Technology Stack

- **Backend**: Node.js 20+, Express.js, TypeScript 5.6+, Drizzle ORM 0.39+, Neon PostgreSQL (serverless)
- **Frontend**: React 18.3+, Vite 5.4+, Wouter routing, Tailwind CSS, Radix UI + shadcn/ui
- **Auth**: Better Auth with email/password, Google OAuth, TOTP MFA
- **Payments**: Stripe (SaaS billing) + Stripe Connect (operator payouts)
- **Email**: SendGrid transactional emails
- **AI**: Multi-provider — Anthropic Claude, OpenAI, Groq, Ollama, Together AI
- **Realtime**: WebSocket with room-based pub/sub
- **Languages**: English, Spanish, Chinese (Simplified), Amharic
- **Database**: 150+ tables across 25 domain modules, 88+ enums, multi-tenant RLS

## Current Status

Beta program active with real operators. Waitlist open for founding member pricing. Features are being trialed and refined with feedback from actual restaurant businesses.

## API & Developer Access

KojiOps exposes a REST API with 500+ endpoints for programmatic access to all platform capabilities.

### API Documentation
- **OpenAPI 3.0 Specification**: https://kojiops.com/api/openapi.json (machine-readable, unauthenticated)
- **Swagger UI**: https://kojiops.com/api/docs (interactive API explorer, unauthenticated)
- **AI Plugin Manifest**: https://kojiops.com/.well-known/ai-plugin.json

### Authentication
API access uses API keys created within the platform. Key management is MFA-gated for security. Keys are scoped per company and can be rotated. Each API request requires a valid key in the Authorization header.

### Public Endpoints (No Authentication Required)
- `GET /api/public/pricing` — Current subscription tiers and usage-based pricing
- `POST /api/public/waitlist` — Sign up for the beta waitlist
- `GET /api/openapi.json` — OpenAPI 3.0 specification
- `GET /api/docs` — Swagger UI
- `GET /health` — Platform health status
- `GET /llms.txt` — This file

### Webhook Endpoints (HMAC-Authenticated)
POS systems push order data via webhooks:
- `POST /api/webhooks/toast/*` — Toast POS events
- `POST /api/webhooks/square/*` — Square POS events
All webhooks are validated via HMAC signature before processing.

### Authenticated Endpoints (API Key Required)
All other endpoints require authentication. Major endpoint groups:
- `/api/companies/*` — Company management
- `/api/locations/*` — Location management
- `/api/operators/*` — Operator management
- `/api/staff/*` — Staff records, scheduling, certifications
- `/api/orders/*` — Order management
- `/api/inventory/*` — Inventory, recipes, purchase orders
- `/api/financial/*` — Revenue splits, settlements, accounting, budgets
- `/api/compliance/*` — Compliance engine
- `/api/workflows/*` — Workflow automation
- `/api/intelligence/*` — AI intelligence, chips, claims, facts
- `/api/analytics/*` — Metrics, projections, dashboards
- `/api/webhooks/*` — Outbound webhook subscriptions

### Rate Limiting
10 requests/minute per endpoint per authenticated user.

### WebSocket (Real-Time)
WebSocket connection at the root URL with session-cookie authentication. Supports room-based pub/sub for:
- Company-wide events (sales updates, exceptions)
- Location-specific events (inventory alerts, shift changes)
- User-specific events (notifications, task assignments)

## Links

- Website: https://kojiops.com
- Pricing: https://kojiops.com/pricing
- Architecture Explorer: https://kojiops.com/architecture
- API Documentation (Swagger): https://kojiops.com/api/docs
- OpenAPI Specification: https://kojiops.com/api/openapi.json
- AI Plugin Manifest: https://kojiops.com/.well-known/ai-plugin.json
- Platform Description (this file): https://kojiops.com/llms.txt