Spensara: how it works, onboarding, tools, workflows and gaps

Prepared 2026-10-23 from the KDSAI codebase (Bematechus/KDSAI, main at f2962c7, 2026-06-24, plus 13 branches; the newest activity is feature/fleet-import, committed 2026-10-23 05:25 ET). Code was read through the xstore Gitea pull mirror, which was in sync with GitHub this morning. Nothing in GitHub or the mirror was changed.

"Spensara" is the product name. In code it is KDSAI / Kds.Ai.*. Do not rename the repo; the mirror depends on the name.

1. What Spensara is

A restaurant monitoring and anomaly detection platform driven by large language models. A manager describes what to watch in plain English ("watch prep times by hour, flag strange slowdowns"). The system turns that into a versioned, executable MonitorSpec, runs it on a schedule against the restaurant's own warehouse data, double-checks its own conclusions, and emits alerts (Name, Summary, Content in Markdown, Severity High/Medium/Low). Managers can also chat with their data.

Thirty example monitor specs ship in backend/Kds.Ai.Data/MonitorSpecs/ (prep time, slow kitchen, station bottleneck, order surge, forgotten items, waste reduction, menu profitability, star and plowhorse items, demand and seasonality forecasts, customer segments and churn, pricing recommendations, inventory levels).

2. Architecture and components

Not in this repo: AWS infrastructure as code. CI deploys to ECS services that already exist; the infrastructure appears to live in separate mirrored repos (KDS.AWS.Devops.Infrastructure, KDS.AWS.Devops.Infrastructure.Core, KDS.Devops), which were not reviewed here.

Agent roles (docs/README.md)

Orchestrator, Spec Builder (talks to the manager), KB / Semantic agent (what data exists and what it means), Data Access agent (the only component that queries data, read-only and tenant-scoped), Runtime Detector (runs the spec as a runbook: preflight, broad scan, drilldowns), Critic / Verifier (blocks weak alerts), Alert Emitter (dedupe and send).

Data platform (docs/ETL.md, docs/flows/etl-ingestion.md)

Four ingestion modes (file upload, API push, API pull, CDC) converge into one path:

source -> S3 raw (immutable) -> normalize to Parquet (S3 load) -> Redshift COPY into tenant staging -> SQL transform into curated -> serving views -> UNLOAD curated Parquet to S3 -> Athena for cross-tenant queries

Rules: the pipeline owns correctness (agents never fix data at query time); checkpoints advance only after a batch succeeds end to end; failed packages are kept for replay; each tenant has its own Redshift database.

3. Brink POS path today (summary; the separate Brink pipeline analysis goes deeper)

• Endpoints: Sales2.GetOrders, Labor.GetShifts, Settings2.GetItems, Settings2.GetEmployees, Settings2.GetJobs (GetDestinations used as a lookup).
• Stages: extract_raw -> normalize_load -> load_to_staging -> staging_to_curated -> curated_to_s3 (export of pos_orders, pos_order_items).
• About 31 staging tables; 7 curated tables (pos_orders, pos_order_items, pos_menu_items, employees, pos_jobs, labor_shifts, pos_destinations).
• Scheduling exists in code: BrinkCronSyncService registers one TickerQ cron per enabled Brink credential. Default is 0 0 1 * * * (01:00 America/New_York) for business date minus 1, with a 2-day lookback (maximum 7). So the code is batch daily, not real time. Where it feels manual today, the likely causes are deployment and configuration (credential disabled, schedule off, worker not running in the deployed environment), not missing code. That needs confirming in AWS.

4. How to onboard a customer (every step)

From the code (AdminCustomerEndpoints, CustomerEtlProvisioningService, TenantWarehouseBootstrapper, the CustomerCredentialTriggeredProvisioning spec) and the docs:

1. Commercial and data prerequisites. Signed agreement; confirm which sources the store runs (Brink, Logic Controls KDS, Aloha, LabPOS, files). Check the franchise agreement for data and third-party software restrictions (see the tracker's Franchise Tech & Data tab).
2. Collect source access. For Brink: access token, location token(s), service URL, per location. For KDS CDC: cross-account SQS FIFO and Debezium connector on the customer side. For files: Fleet landing access and a manifest contract.
3. Create the customer (admin API / admin UI): company, solutions enabled (PUT /customers/{id}/solutions). This creates the tenant id.
4. Create users and roles in Keycloak and link them to the customer (membership drives tenant scoping; the front end never sets tenant headers itself).
5. Add the source credential (POST /customers/{id}/api-keys). Credentials are encrypted at rest (data-protection envelope). Optional custom headers and a schedule (time zone, cron, lag, lookback, enabled) are stored with it.
6. Provisioning runs. Saving a credential provisions the tenant warehouse: register the Redshift database, then bootstrap staging tables only for enabled sources plus all curated and serving objects. On main this blocks customer create/update for about 30 seconds; the spec moves it to an asynchronous TickerQ job with visible status.
7. Schedule registration. On startup and on change, the cron sync service creates or updates the TickerQ cron for the credential.
8. Backfill. Run the ETL for historical business dates (lookback is capped at 7 days per run; longer history needs repeated or replay runs).
9. Verify data. Row counts per staging and curated table, freshness, failed packages empty, curated Parquet present in S3.
10. Knowledge base. Run KB generation (knowledge-base CLI): capabilities manifest (tables, joins, units, freshness), KPI catalog from the restaurant's manuals and SOPs, document index.
11. Monitors. Seed or author MonitorSpecs with the manager; backtest; approve and enable; set cron.
12. Alerts. Configure recipients (email, SMS); confirm a test alert arrives.
13. Hand over. Manager login, short training, support contact.

Not yet automated or productized: self-service onboarding, a tenant admin control plane (designed on branch tenat-admin, not built), store groups and multi-store access, Fleet schema approval (branch feature/fleet-import), and a documented runbook for offboarding.

5. Tools used to process data

6. Workflows

1. KB generation (docs/flows/kb-generation.md): schemas and vendor docs -> profiler -> join mapper -> capabilities manifest; manuals -> KPI extractor -> KPI catalog and document index.
2. Monitor authoring (monitor-authoring.md): manager prompt -> Spec Builder -> feasibility check against the KB -> backtest -> revise -> approve and enable.
3. Runtime execution (runtime-execution.md): cron -> load spec -> preflight freshness -> broad scan -> drilldowns -> critic -> emit alert -> record run history and dedupe.
4. ETL ingestion (etl-ingestion.md): the five stages above, per tenant, with checkpoints, failed packages and replay.
5. KDS CDC (docs/features/ETL/kds-cdc/): SQS micro-batches -> raw -> Parquet -> staging -> curated -> export, with quarantine and a replay coordinator.
6. Fleet pre-ingestion (branch): customer uploads one file plus a manifest -> schema version checked against an approved contract registry -> validated -> published to raw/source_type=fleet -> standard ETL. This is the closest existing design to the "Borg" idea (shape and approve before anything enters the pipeline).
7. Customer onboarding and provisioning (section 4).
8. CI/CD: pull request build and test -> merge to main -> images to ECR -> ECS rollout.
9. Development method: work is driven by specs/<Feature>/TASK*.md files and agent guidance (AGENTS.md, .agents/skills/). Euvic builds with coding agents and leaves the spec trail in the repo, which makes handover easier.

7. Gap analysis: what remains for a fully finished product

Severity: P1 blocks paying customers, P2 needed for scale, P3 polish.