Documentation

This page is the cold-start manual for this portal. It is written so that a new operator — a person on their first day, or an AI assistant with no prior context — can understand, run, and safely change the system using nothing but this page and the repository. Every Botworks client build ships a page exactly like it.

Try it yourself: open your AI assistant (Claude, ChatGPT — whichever you use), paste this page in, and ask it to explain how a visit becomes a crew task list, or how you'd add a new field to the capture form. It will tell you, correctly, because this page is the real manual for the real code. That is what owning the code means.

What this app does, and why

An account manager walks a property and sees things: work that needs doing, problems worth photographing, notes the office should know. Without a system, those observations live in texts, voicemail, and memory — they get copied, chased, retyped, or forgotten. This portal replaces that with a three-step flow:

Capture (the Visit Capture page): the account manager picks the property, types or dictates notes, adds work items, attaches photos. Built for a phone in a parking lot. Available in English and Spanish.
Review (the Review page): the office sees every submitted visit in one table — status, photo count, work items — and moves each through a simple lifecycle: New → In review → Tasks sent → Closed.
Outputs (the payoff, one click from any Review row): the work products generated the moment a visit is submitted — bilingual crew task lists, work items queued for the ticketing system, a drafted client follow-up email, and a print-ready report.

Where AI does the work — and where it doesn't

Every capability in this portal carries one of two labels, because the distinction matters when you're deciding what to buy:

AI — a model does the work: translating work items into Spanish, routing them to the right crew, and drafting the client email. These are the minutes-per-visit of office labor that disappear. In this demo the AI outputs are simulated client-side (see lib/comms.ts); in a production build they are real model calls at submission time.
Custom build— plain, solid software with no model involved: the capture form, the review table, auth, deploys, this documentation. It doesn't need AI, so it doesn't use AI.

That honesty is deliberate. Vendors who wave "AI" over everything are usually hiding which parts are a database query. You should always be able to point at a feature and know which kind of value you're paying for.

Data model

There are three entities. In this demo they live in your browser's localStorage (so anyone can play without touching shared data); in a production build the identical shapes live in Postgres tables.

Property — id, name, address. Seeded from the skin config (lib/skins.ts); in production this is the client's real properties list, usually synced from their CRM or maintained on an admin page.
Submission (one visit) — id, propertyId, fieldStaff, submittedAt, status, generalNotes, tickets[], photos[]. Defined in lib/demo-data.ts.
Ticket (one work item) — service (from the skin's services list), note and noteEs (the bilingual instruction pair), and crew (which crew it routes to).

Status lifecycle: new → in_review → tasks_sent → closed. The Review page is the only surface that changes status.

User roles

Account Manager — uses Visit Capture on a phone. Creates submissions; never needs the Review page.
Office / operations — lives in Review on a desktop. Triages submissions, sends task lists, closes the loop.
Crew — receives the bilingual task list. In production this lands in their task tool or messaging app; in the demo you view it from the Review page.
Owner — reads this page, the Ownership page, and Status. Owns the repo, the database, and the deployment.

The demo has no login. Production builds use email one-time-code sign-in with an allowlist — no passwords to manage, no accounts to provision beyond adding an email address.

How the code is organized

app/ — one folder per page (Next.js App Router). The root pages serve the default skin; app/[skin]/ serves the same surfaces re-branded per prospect config.
components/surfaces/ — the actual page implementations (capture, review, task list, documentation, ownership, status). Route files are thin wrappers, so every skin shares one implementation.
components/ui/ — the design system: buttons, cards, tables, badges. Shared across every Botworks build.
lib/skins.ts — the white-label layer: company name, accent color, industry terms (Property vs Property, Account Manager vs Account Manager), services, seeded properties.
lib/demo-data.ts + lib/demo-store.ts — data shapes, seed data, and browser-side persistence.
lib/comms.ts— the demo's simulated AI outputs (client email drafting, ticket-push payloads). The seam where a production build swaps in real model calls and real integrations.

Integrations

This demo deliberately has none — no database, no email, no external APIs — so it can never break mid-pitch and never touches real data. Production builds on this same pattern typically wire:

a hosted Postgres database (the client's own project, in their billing account) as the system of record;
task delivery into whatever the crew already uses — shared task apps, email, or print views;
lookups against the client's existing systems (CRM contacts, price books, customer lists) so dropdowns stay true without retyping.

Deploy and rollback

The repository is the single source of truth. Every push to main auto-deploys: the hosting platform builds the app and swaps it live, typically in under two minutes. Rollback is selecting the previous deployment in the hosting dashboard and clicking "promote" — no terminal, no engineer required. The owner has dashboard access to all of it.

Health: /api/health returns JSON the monitoring system polls; the Status page renders the same picture for humans.

Recent changes

2026-06: Outputs page added (the AI showcase). Why: the original demo buried the most valuable part — what AI generates from each visit — behind a plain task-list view. Now every submission shows its four work products, each labeled AI or custom build.
2026-06: Initial demo portal build. Why: prospects kept asking "what does owning the code actually mean?" — this portal is the show-don't-tell answer, and each prospect can get a skinned copy at their own URL.

In client builds this section is maintained with every change, in plain language, with the business reason — not commit jargon. It's the change log your team (and your AI assistant) actually reads.

How your AI assistant maintains this

This is the part that makes ownership practical rather than theoretical. Because you own the GitHub repository, any capable AI assistant can be pointed at it and asked to:

Explain anything. "How does a visit become a task list?" — it reads components/surfaces/ and tells you.
Make small changes. "Add a 'priority' field to work items." — the shapes in lib/demo-data.ts, the form in capture.tsx, and the table in review.tsx are each a few readable lines.
Diagnose problems. The health endpoint, this manual, and a readable codebase mean "why is X broken?" is answerable without the original developer.

Nothing here is exotic: it's a standard Next.js + TypeScript app, the most common stack AI assistants know. That's a deliberate choice — boring technology is what keeps your options open. If Botworks disappeared tomorrow, you'd hire any web developer, or increasingly, just ask your own AI assistant.

What's different from a production build

Data lives in your browser here; in Postgres in production.
No login here; one-time-code email auth in production.
Task lists render on screen here; in production they also deliver to where the crew already works.
Everything else — the surfaces, the design system, the docs pattern, the deploy pipeline — is the real thing.