# LOLE OS

> LOLE OS is the staff-only operating layer for LOLE Boutique: Admin, POS, and Developer shells over Shopify commerce truth, Supabase operational state, contribution reporting, controlled AI, and platform health. Built as independent contractor client work.

- HTML: https://estebanech.com/projects/lole-os
- Markdown: https://estebanech.com/projects/lole-os.md

## Shopify runs commerce. LOLE OS runs the operation.

LOLE OS is the staff-only operating layer for LOLE Boutique, connecting online commerce, the physical store, inventory, customers, contribution reporting, AI-assisted workflows, and platform control in one application. Shopify remains the commerce source of truth. LOLE OS turns that data into the workflows staff actually use to run the business.

## Metadata

- Role: Freelance Software Engineer
- Client: LOLE Boutique
- Surfaces: Admin · POS · Developer
- Languages: English · Spanish
- Delivery: Feature Freeze v1.0
- Repository: Private

## Overview

LOLE Boutique already had Shopify for commerce. What it did not have was one place for staff to operate the business around it.

Orders lived in one workflow. Inventory required additional context. Physical-store sales needed a floor interface. Product costs, contribution, customers, suppliers, invoices, social activity, and platform health each introduced another operational surface.

LOLE OS brings those workflows together without replacing the systems that already own the underlying truth.

Shopify owns commerce. Supabase owns operational state. LOLE OS owns the staff workflow.

## Problem

Boutique retail operations fragment across Shopify Admin, spreadsheets, invoice inboxes, messaging, and ad-hoc floor processes. Staff needed a secure internal surface that interprets business reality without replacing Shopify — and without inventing financial numbers through unconstrained AI.

The engineering question became:

> How do you build the operational layer a real retail business was missing — online, floor, money, clients, AI, and platform control — while keeping Shopify as commerce truth and numbers deterministic?

## Solution

### Admin shell

Business operations: orders, inventory and costs, contribution, customers, providers, collections, marketing, invoices, and staff access.

### POS shell

Floor register for in-person sales — product search, cart, cash/card/Zelle recording, inventory deduction, and same-day operational reflection.

### Developer shell

Platform control room: integration health, sync age, jobs, webhook failures, feature flags, AI spend, and kill switches.

### Commerce data spine

Shopify remains authoritative. Webhooks and a Railway worker keep Supabase mirrors fresh. LOLE OS reads and writes through authorized server paths.

### Controlled AI

Invoice vision, grounded staff assistance, and daily briefs — models extract or narrate; application code owns numbers and mutations.

## Capabilities

### Store Floor

For staff actively running the physical location. POS register, Today's sales, Inventory lookup, Client lookup, Sales history, and more.

### Business Operations

For managing the broader company. Shopify orders, Inventory and costs, Providers, Contribution reporting, Customers and VIP signals, and more.

### Platform Operations

For operating LOLE OS itself. Integration health, Sync status, Jobs, Webhook failures, Audit trail, and more.

## Thesis

Shopify owns commerce. Supabase owns operational state. LOLE OS owns the staff workflow.

## From floor to back office

### Sell in person

POS → Select products → Record payment method → Create pos_sale → Deduct inventory → Optional Shopify write → Revalidate operational views

Floor sales are recorded directly inside LOLE OS. Staff search the live product mirror, build a sale, record cash/card/Zelle payment, update inventory, and immediately reflect the transaction across store operations.

> LOLE records floor payments. It does not process them.

### Receive inventory from an invoice

Invoice image/PDF → Vision extraction → Staff review → Product / SKU match → Inventory + cost apply → Revert snapshot

AI extracts. Staff approve. Application code applies.

### Understand what the business actually made

Online orders → POS sales → Revenue → − COGS → − Shipping absorbed → Contribution

Finance views calculate contribution deterministically from operational data. Models can explain the result, but they do not produce the number.

## Operating planes

### Store Floor

For staff actively running the physical location. POS register, Today's sales, Inventory lookup, Client lookup, Sales history, Finance snapshots, AI assistant.

### Business Operations

For managing the broader company. Shopify orders, Inventory and costs, Providers, Contribution reporting, Customers and VIP signals, Collections, Marketing, Subscribers, Invoice intake, Staff access.

### Platform Operations

For operating LOLE OS itself. Integration health, Sync status, Jobs, Webhook failures, Audit trail, Feature flags, AI cost, AI kill switches, Environment presence.

## Fresh by webhook. Correct by reconciliation.

Shopify data reaches LOLE OS through two paths. Webhooks deliver fast, entity-level updates after Shopify changes. A Railway worker periodically catches missed or delayed state and recomputes operational data.

- Webhook: Immediate mirror update
- Worker: Reconciliation / repair

Webhook deliveries are deduplicated before application.

## The store has its own interface

The floor does not need the same interface as the back office. LOLE OS switches into a dedicated POS shell under /pos, retaining the same data and authorization layer while simplifying navigation around the tasks needed during a sale.

> Same application, same authorization, same underlying data, different operational context.

## AI can help. It cannot redefine the business.

### Invoice Vision

Document → Extract → Review → Apply

Never silently invent unreadable quantity or cost values.

### LoleAI

Staff question → Read-only business tools → Supabase mirrors → Answer

Grounded in live operational data, not a giant business prompt.

### Daily Briefs

Precomputed metrics → LLM narration → Today

Code computes. The model explains.

## Engineering Decisions

### Shopify remains the commerce source of truth.

LOLE OS mirrors commerce data and adds internal operational context without replacing Shopify's responsibility for products, inventory, orders, and customers.

### Supabase owns operational state.

Auth, staff profiles, mirrors, POS sales, costs, alerts, AI history, audit trails, and feature flags live in Postgres with RLS.

### Three shells, one application.

Admin, POS, and Developer share authorization and data while presenting context-appropriate navigation and density.

### Fresh by webhook, correct by reconciliation.

Entity webhooks keep mirrors current; a background worker repairs missed or delayed state and recomputes operational data.

### Deterministic numbers before AI.

Contribution, shipping absorption, stock logic, and period metrics are computed in code. Models explain; they do not invent KPIs.

### AI extracts and narrates under human control.

Invoice vision requires staff approval before apply. Assistant tools are read-oriented. Kill switches disable AI surfaces without redeploying.

### Server-side authorization only.

Roles resolve from authenticated server state via getActor(). Client-supplied roles are never trusted.

### Business time is a system concern.

Store timezone drives “today” and period reporting so floor and finance views match the boutique's operating day.

## What LOLE OS is not

- Not a storefront
- Not a Shopify theme
- Not a Shopify Admin clone
- Not a payment processor

It is the operational layer around the business.

## Highlights

- 03 shells — Admin · POS · Developer
- 02 languages — English · Spanish
- 02 commerce freshness paths — Webhooks · reconciliation
- 01 commerce source of truth — Shopify
- 01 operational database — Supabase Postgres + RLS
- Global kill switches — AI · sync · Shopify writes · health
- Separate worker plane — Railway background processing

## Technology

### Application

- Next.js 16
- React 19
- TypeScript
- Tailwind
- Zod
- next-intl

### Data & auth

- Supabase Auth
- PostgreSQL
- Row-Level Security
- Supabase Storage

### Commerce

- Shopify Admin GraphQL
- Shopify Webhooks
- Signed deliveries

### AI & workers

- OpenAI
- Vercel AI SDK
- Railway worker
- Docker

## Status

LOLE OS was delivered as a freelance independent contractor engagement at Feature Freeze v1.0. Platform access and ownership belong to LOLE Boutique.

The production repository remains private because it contains client configuration, integration handling, operational workflows, and internal business logic. This case study describes architecture and engineering responsibility without exposing secrets, customer data, or confidential strategy.

Built by Andres Echeverria as sole engineer. This is not employment at LOLE Boutique.

## Next Steps

- Sanitized product screenshots for the public case study
- Expand messaging and operational alerts under existing auth and flags
- Harden reconciliation and webhook failure diagnostics
- Deepen contribution and inventory reporting on deterministic pipelines
- Improve bilingual operator documentation

Author: Andres Echeverria (estebanech)