Tutorials

Complaints, end to end

Every component kind in one working service: a resident photographs a pothole, files it over Telegram, and the city tracks it to a verified closure — while the same spine proactively pulls complaints from news and social feeds, and an AI expert helps staff and vendors resolve them and find permanent fixes.

This is the capstone to Writing components. There you saw each kind alone; here they compose into one solution — a pinned member-graph a city installs in one step. We use a real target: a complaints service for a large municipal tenant.

The use case

A resident sees a civic problem — an overflowing bin, a broken streetlight, a flooded lane. They should be able to report it from where they already are (a chat app), with a photo, in their language; get a ticket; check status; and be asked to confirm when it's fixed. The city should see every complaint — not only the ones filed directly, but the ones surfacing in the news and on social media — on one queue, with the context staff need to act: the guidelines that apply, the vendor contract that covers that ward, the asset inventory, the terrain and drainage, and what happened the last ten times a complaint like this came in nearby.

The challenges this raises — and the kind that answers each:

The shape

Everything hangs off one governed record — city.complaint — and the universal Inbox & Case spine. Each kind only ever touches that spine through the broker; no component talks to another directly.

Build it, member by member

1 · Govern the vocabulary first. Before any code, propose the nouns and verbs this service needs — city.complaint (the record), its status values, and the lifecycle verbs (file, assign, resolve, confirm-closed). Governance is shared, so reuse what exists (the generic Inbox/Case + lifecycle verbs) and propose only what's genuinely new. See Designing a schema and Designing a verb.

2 · The adapter — file + track over Telegram. The confined Telegram adapter from Writing components → Adapter. A message with a photo opens a city.complaint (the photo goes to the filestore, its digest onto the record); a message like "status NDMC-4821" reads the case back; and when work closes, the adapter asks the resident to confirm the fix — their reply flips the case to closed-confirmed or re-opens it. The bot token is a per-tenant Vault secret; the admin clicks Activate in Settings → Components.

3 · The driver — proactive intake. A driver that polls news and social feeds (declared egress, key in Vault), extracts civic complaints, geocodes them to a ward, and writes them as city.complaint with source: news — so a pothole trending online lands on the same queue as one filed by hand, deduped against existing open cases.

4 · The engine — hotspots → permanent fixes. An engine exposing complaint-hotspots: it reads all open and historical complaints, clusters them by location and category, joins terrain/drainage and asset inventory, and writes a ranked list of hotspots with a proposed permanent fix (a governance.recommendation) — e.g. "re-grade this lane; 23 flooding complaints in 3 monsoons." It computes; it never decides.

5 · The skill + agent — track to closure, help resolve. A skill per job (triage-and-route, draft-a-resolution-plan, check-against-guidelines) and an agent — the Complaints Expert — that bundles them under one persona. Each skill reads the case plus the grounding a resolver needs — guidelines, the ward's vendor contract, asset inventory, terrain, hydrology, and the history of nearby complaints — and proposes a cited next step for staff or the vendor. Every suggestion cites the records it stands on.

6 · The app — the Complaints Desk. A sandboxed app showing the queue, each case's full context and the Expert's cited suggestions, with the action buttons (assign, resolve) that call the governed verbs as the signed-in officer. Residents need no app — they're on Telegram.

Pin them into a solution

A solution is the member-graph plus the governed vocabulary it depends on. Declared once, it installs as a unit — each member gets its per-tenant run token and grants, exactly the reads/writes/egress/secrets it certified.

# solution meta — the pinned graph a city installs in one step
component_id: ds:<tenant>:solution/complaints
kind: solution
version: 0.1.0
provider: ds:<tenant>:developer
display_name: Citizen Complaints
members:
  - ds:<tenant>:adapter/telegram-concierge     # file + track + confirm closure
  - ds:<tenant>:driver/complaints-intake        # news + social → city.complaint
  - ds:<tenant>:engine/complaint-hotspots        # clusters → permanent-fix recommendations
  - ds:<tenant>:agent/complaints-expert          # bundles the resolution skills
  - ds:<tenant>:app/complaints-desk              # the officer's queue
requires_schemas: [city.complaint, governance.recommendation, platform.case, platform.inbox_item]

Install it into the city tenant; set the Telegram token in Settings → Components; click Activate. The service is live — residents file, the desk works the queue with the Expert's help, the hotspot engine runs on a schedule, and the intake driver keeps pulling.

Back to the challenges

• File + track from a channel we don't own → the adapter, confined, token in Vault.
• Don't miss unfiled complaints → the driver, feeding the same city.complaint spine.
• One queue, one shape → the governed schema + Inbox/Case; every source normalises to it.
• Cluster + permanent fixes → the engine, proposing cited governance.recommendations.
• Help staff & vendors resolve → the agent + skills, grounded in guidelines, contracts, assets, terrain and history.
• A desk to work it → the app, acting as the officer.
• Install in one step → the solution.

Seven kinds, one record, one certified install — and nothing in it can touch anything it didn't declare. That's the whole point of composing on AirawatOS: each piece is small and auditable, and the governance holds across all of them at once.

Build each member with Writing components; govern its vocabulary with Designing a schema / a verb; ship each with Build, test, publish.