Architecture & integration
reference

01

Overview & design principles

TellUs is a platform-agnostic visual feedback widget. A non-technical reviewer opens a client site with a single activation link, clicks elements, types notes, and submits. Feedback is captured as structured, machine-readable data your AI coding agent can act on directly — without a clarification round-trip.

The project ships as three independent sub-stacks: a vanilla-JS widget bundle, a procedural PHP API, and a vanilla-JS dashboard SPA. They share no framework, no monorepo tooling, and no build step beyond the widget's esbuild compilation.

Five design principles

02

Architecture

Three sub-stacks; no monorepo tooling. The root package.json owns test tooling (Playwright) only. Key architectural decisions are recorded as ADRs in docs/adr/.

Three sub-stacks

Widget internals

The widget is compiled by esbuild into an IIFE bundle plus two optional lazy chunks. The core bundle contains activation detection, the UI shell, the element selector, and note submission. Screenshot and voice capture are not shipped to clients who never use them — they are fetched and evaluated on first use only.

Bundle budget

Hard budget: core ≤ 25,600 bytes gzip. Verify with bash scripts/check-bundle-size.sh.

API directory structure

api/                    # PHP API (procedural, PDO/MySQL, no framework)
  cli/feedback.php      # Agent-facing CLI — progressive-disclosure DB queries
  config.php            # DB factory, constants, rate limits; bootstrapped first
  index.php             # Front controller (.htaccess rewrites here)
  endpoints/            # Route handlers: auth, sites, sessions, notes, reports, upload, media
  middleware/           # CORS (widget vs admin) + session auth
  models/               # DB helpers: site, session, note
  lib/webhook.php       # Webhook dispatch + retry
  migrations/           # Numbered .sql files, applied by migrate.php
dashboard/              # Vanilla HTML/JS SPA (ES modules, no build step)
widget/                 # esbuild IIFE bundle + lazy chunks
  src/                  # Source modules
  dist/                 # Built output — gitignored; must build before deploy
docs/                   # ADRs, self-hosting guide, glossary, runbook

Database schema overview

MySQL 5.7+ / MariaDB 10.3+. Tables: sites, admin_users, admin_sessions, sessions, notes, webhook_log, rate_limit, schema_migrations. JSON columns: class_list, bounding_box, computed_styles, pages_visited.

03

Auth model

Widget trust: Origin allow-list

The widget embed is a plain <script> tag with no secret. When the widget submits a note, the API resolves trust by matching the HTTP_ORIGIN header against the sites.domain column in the database (api/middleware/cors.php → apply_widget_cors()). If the domain is registered, the request is accepted. No key to provision, rotate, or accidentally expose in source.

The practical consequence: a key in a <script> tag is not secret — anyone viewing source can read it — so API keys would add management overhead with no real protection. Origin-based trust gives equivalent assurance with a zero-secret embed.

Admin auth: HttpOnly session cookie

Dashboard login sets a tellus_admin HttpOnly session cookie (api/config.php → TELLUS_COOKIE_NAME). The cookie is not readable by JavaScript and fits a browser-only admin surface. Single-user admin model — one account, no roles, no multi-tenancy. There is no admin bearer token.

04

Data model & selectors as agent targets

Every note is a structured capture of the clicked element's identity and visual state at annotation time. The data is designed for a coding agent — not a human reading a ticket.

Captured fields per note

The triple-anchor model

Each note stores three independent ways to re-locate the same DOM element: a CSS selector, a structural XPath, and a text-content XPath. An agent that can act on the CSS selector alone never needs the others. When a page refactor changes class names, the structural XPath still works. When position and class names both change but the text content is unique, the text XPath finds it. The triple-anchor system makes element location resilient to page evolution.

Note status flow

Every note moves through four states, supported by both the dashboard and the CLI:

told means "acknowledged and communicated to the reviewer" — the status between open and resolved. Resolved notes can be reopened. Archived notes are hidden from the default dashboard view but remain in the database.

05

Two-layer report API

Feeding the full forensic payload of every note to an agent wastes context budget. Discarding detail means the agent can't self-serve when a summary is ambiguous. TellUs resolves this with a two-layer design: a sparse summary for bulk scanning, and a full detail endpoint queried only when needed.

Layer 1 — Summary

Endpoint: GET /api/reports/{domain}/summary

Optional query param: ?status=open (or told / resolved / archived). Defaults to all open notes. Returns ~250 bytes per note. An agent acting on most notes never touches Layer 2.

{
  "site": "example.com",
  "session": {
    "reviewer": "Jan Smith",
    "device": "desktop / Chrome / macOS",
    "viewport": "1440×900"
  },
  "notes": [
    {
      "id": "note-uuid-001",
      "page": "/about",
      "selector": ".hero-section h2",
      "currentText": "Welcome to Our Site",
      "comment": "Change to our actual studio name",
      "replacementText": "Smith Creative Studio",
      "type": "text-change",
      "detailRef": "note-uuid-001"
    }
  ]
}

Layer 1 fields per note: id, page, selector, currentText, comment, replacementText, type, detailRef. The detailRef is the handle an agent uses to request Layer 2.

Layer 2 — Detail

Endpoint: GET /api/reports/{domain}/detail/{noteId}

Full forensic payload for one note. Queried only when the Layer 1 summary is insufficient to act — for example, disambiguating which .price element on a page with three. Returns the triple anchor (cssSelector, positional xpath, text-content xpathText), computed styles snapshot, bounding box, reviewer session context, screenshot URL, and voice transcript.

06

Embedding & activation

The embed snippet

Add one script tag to the site's HTML, once, before </body>:

<!-- Add once to your site; no key, no configuration -->
<script defer src="https://tellus.alchemygraphics.com/widget/dist/tellus.min.js"></script>

No API key. No data-key. The widget is trusted because the site's domain is registered in the TellUs dashboard. Until ?tellus= appears in the URL, the script does nothing — it is completely dormant for production visitors.

Self-hosted instance override

To point the widget at a self-hosted TellUs instance instead of the public one, add data-tellus-api:

<script defer
  src="https://your-host/widget/dist/tellus.min.js"
  data-tellus-api="https://your-host/api"></script>

Activation link pattern

The widget activates only when a URL contains ?tellus= with a reviewer email address:

# Construct a link for the reviewer
https://yoursite.com?tellus=reviewer@email.com

# Deactivate the widget for this session
https://yoursite.com?tellus=off

The email address becomes the webhook and notification target. A 24-hour session cookie persists activation across page navigations on the same site — the reviewer does not need to re-click the link to leave notes on a different page. ?tellus=off explicitly deactivates the widget for the current session.

The four gestures

07

CLI reference

The CLI is intended for developer and agent use. It queries the database directly on the server — no HTTP auth required. Run it via SSH against the deploy host.

# Sparse scan — covers ~90% of use cases
php api/cli/feedback.php example.com

# Full detail for one note
php api/cli/feedback.php example.com --detail note-uuid-001

# JSON output for agent consumption
php api/cli/feedback.php example.com --json

# Status transitions
php api/cli/feedback.php example.com --told note-uuid-001
php api/cli/feedback.php example.com --resolve note-uuid-001 --comment "Fixed in header.php"
php api/cli/feedback.php example.com --reopen note-uuid-001

# Delete a note and its associated media
php api/cli/feedback.php example.com --delete note-uuid-001

Verb reference

08

Self-hosting

TellUs is MIT-licensed and designed to run on plain shared hosting. No Docker, no Composer, no framework. A competent PHP developer can be running their own instance in under an hour.

Prerequisites

Setup sequence

09

Feature tiers & roadmap

TellUs is built progressively. Tiers 0–2 are shipped and available now. Tier 3 is on the roadmap.

License

TellUs is MIT licensed. You can run it on your own server, fork it, and modify it freely. No SaaS subscription. No vendor lock-in. The only cost is your own hosting.