CivicLoop by Ta-Tech Solutions Purpose: Every screen on every surface, at wireframe level, and the end-to-end journeys that connect them. This is what the build team implements and what the demo on May 23 walks through.
| Screen | Purpose |
|---|---|
| Home / Report | The front door. One big "Report a problem" action; below it, "Track a request" and the public map. |
| Conversational intake | The AI-guided report flow - voice or text, in any language. Capture category, location, photo, description. Accepts ?address=&lat=&lng= from a QR or SMS deep-link so a scan pre-fills the location. |
| Confirm & submit | Review what the AI captured, fix anything, confirm. Issues the request number. |
| Report success | Success screen with the tracking number, the resident-friendly summary, AND a tracking QR generated server-side via /api/qr?data=... - a phone scan jumps straight to /track?number=&phone= and auto-runs the lookup. |
| My requests | The resident's list of filed requests with live status. |
| Request detail | One request: status, timeline, the conversation thread, attachments, resolution proof. |
| Public map | All requests in the area as map pins, generalized for privacy, color-coded by status. |
/[locale]/survey/[token] |
The one-tap 1-5 survey page. No auth, no PII; the single-use token IS the credential. The link is texted/emailed to the resident the moment a request transitions to RESOLVED (via web/src/lib/survey/send.ts). |
/public (transparency portal) |
Anonymous, no account, NOT locale-scoped (one URL). Last-7-day filed/resolved/open/median resolution/SLA on-time/NPS, top categories, by-district, an anonymized SVG scatter map. "Save / print PDF" button and a machine-readable CSV at /api/public/weekly.csv. Designed so the press, the Council, and any resident can read it. |
/[locale]/pitch-card |
Bilingual printable handout with a QR. Built so a community-relations staffer can hand a card to a resident at a meeting, the QR scans into the report flow, and the resident files in under a minute. |
| Settings | Language, notification channel, optional account / PIN. |
| Screen | Purpose |
|---|---|
| Queue | The agent's work list - requests routed to their department, prioritized, with SLA timers. |
/console/[requestNumber] request workspace |
The full working view of one request: everything the resident sees plus internal notes, the AI rationale, workflow controls, attachment upload. Progress photo upload is now allowed in assigned status, not only in_progress, so a dispatched crew can post evidence the moment they arrive. The workspace also carries a Schedule a visit action (web/src/components/console/schedule-visit.tsx) and a Visits list panel (web/src/components/console/visits-list.tsx) - pick a date/time, alarm window, and notes; the resident gets SMS + email + a .ics calendar invite. |
/channels channel list, /channels/[slug] channel |
Slack-style per-department channels (DPWT, DOE, WSSC, DPIE, PARKS, ANIMAL, 311), plus a county-wide #311-all. @mention highlighting, substring search, and any CP-... tracking number is auto-linked and deep-links straight into /console/[requestNumber]. Slash commands (/help, /open, /breaches, /summary CP-...) are deterministic, no AI call. @loop triggers a reply from the Loop AI persona (Document 07). |
| Map view | The department's open requests on a map - useful for clustering field trips. |
| Department dashboard | Supervisor / department-head view: volume, SLA compliance, agent workload, the department's heat-map slice. |
| Escalations | The queue of sentiment-flagged, safety-flagged, and predicted-breach requests. Also includes self-heal-triggered escalations (Document 07, Component L). |
| Saved views | The user's filtered queues. |
| Screen | Purpose |
|---|---|
| County overview | The single screen: county-wide volume, category mix, SLA performance, languages served, live counters. |
| Heat-map | The geographic view on the actual PG County map. One dot per request, color-encoded (red = SLA breached, amber = high/urgent, blue = in progress, green = resolved). Filters: All / Open / Breached. Click any dot opens the agent workspace for that request in a new tab. Built on maplibre-gl + OpenFreeMap tiles, no API key required. Live as of 2026-05-18. |
| Trends | Volume and SLA over time; routing accuracy; the patterns that drive staffing and budget decisions. |
| Equity panel | Response-time disparity by council district. Median resolution and SLA on-time % per district, plus a single-line headline ("District X waits 2.3x longer than District Y"). Driven by web/src/lib/dashboard/equity.ts and web/src/components/dashboard/equity-panel.tsx. The data comes from the new service_areas.council_district / locations.council_district columns. |
| Forecast panel | Per (category, council_district): expected request count for the next 7 days computed from a 12-week mean times recent seasonality, with a confidence score. A "Run forecast now" button lets the Director compute on demand. Persists to predicted_issues. Files: web/src/lib/predict/forecast.ts, web/src/components/dashboard/forecast-panel.tsx. |
| NPS panel | Avg score, CSAT %, NPS - rolled up from request_surveys. Driven by web/src/lib/dashboard/nps.ts and web/src/components/dashboard/nps-panel.tsx. |
| Upcoming visits panel | The next scheduled visits across the County (or the scope of the role-holder), drawn from scheduled_visits. Lets a Director see what crews are committed to in the next 48 hours. |
/council/[district] scoped view |
The whole director picture, scoped to one of PG County's 9 council districts. Totals, open, resolved, SLA breaches, top categories, recent requests, and the district's slice of the forecast. Files: web/src/lib/council/data.ts, web/src/app/[locale]/council/[district]/page.tsx. |
| Reports & export | Pull a report, run the open-data export, generate the branded PDF. |
| Screen | Purpose |
|---|---|
/admin operations console |
The County admin's single landing page. Carries the Autopilot dial (web/src/components/admin/autopilot-dial.tsx) - one control with three positions, off / route / full, persists to counties.autopilot_level, every flip is audit-logged. Carries a self-heal "Run now" button that fires web/src/lib/autopilot/heal.ts on demand. Quick links to categories, departments, integrations. The dial is the closing move in the live demo (Document 13). |
/[locale]/admin/locations poster builder |
County-admin tool to mint a printable poster with a QR for any council district, kiosk, or known problem area. Inputs: address, lat/lng, source label. The QR encodes /report?address=&lat=&lng=&source= so a scan auto-fills the report flow. Output: a branded PDF (Document 08). |
| Categories | The service-category tree with default routing + SLA. |
| Routing rules | The routing-rule catalogue. |
| SLA policies | The SLA policy library. |
| Departments & staff | Manage departments, staff, roles, permission grants. |
| Integrations | Open311 endpoint, MyPGC/govDelivery feed, SMS/WhatsApp/email, maps, the SELFHEAL_CRON_TOKEN for the cron endpoint. |
| Branding & languages | Logo, colors, supported languages, notification templates. |
| Audit log | The immutable action log, searchable. |
The Director Dashboard is not a static report. It is a live operating picture of the County's service function, and it is one of the two things (with the hero flow) built to full presentation polish for May 23.
Real-time. The dashboard updates as events happen - a request submitted, a status changed, an SLA clock crossing a line. The counters move while you watch. There is no "refresh" and no overnight batch; the event-driven core (Document 07, Section 7b) pushes changes to the screen as they occur. A Director can put this on a wall monitor and it is always current.
Visual. Every number is also a picture, because leaders make decisions off shapes faster than off tables:
Intelligent. The dashboard does not just plot what happened - the Trend Detection component (Document 07, Component F) and the Director's briefing agent (Document 07, Section 7c) push trend cards onto it: "Road-hazard reports on the Annapolis Road corridor are up 240% over the 90-day baseline" - with the chart, the evidence, and a suggested action. The Director is told what to look at, not left to find it. That is the difference between a dashboard and an intelligence picture - and it is precisely the "weak analytics" failure mode (Document 02) turned into a strength.
The same visual, real-time treatment scales down to the Department dashboard (a supervisor or department head sees their slice) - same components, scoped by role (Document 04).
This is the flow the entire demo is built around. Every screen it touches must be polished to presentation grade.
Maria opens CivicLoop. One dominant button: Report a problem. Secondary: Track a request, View the map. Language selector top-right (she sees it is already on Spanish, or sets it). No login wall. She taps Report a problem.
A simple chat-style screen with a large microphone button. Maria taps it and says, in Spanish:
"Hay un bache grande en Annapolis Road cerca de la escuela, casi se me va la llanta."
CivicLoop:
The whole thing is a conversation, not a form. If she had typed instead of spoken, same flow. If she were offline, the screen tells her it will submit when she is back online.
A clean summary card: Pothole - Annapolis Road near [school] - photo attached - High priority. Maria taps Submit. She immediately sees:
She has spent under a minute. She never called. She never waited on hold. She never made an account.
Behind the screen, in seconds:
On the DPWT Queue, Maria's request is near the top - High priority, SLA clock running. The agent opens the Request workspace:
The agent taps Claim. Status -> ASSIGNED. Maria automatically gets a text in Spanish: "A crew has been assigned to your pothole report."
Day 2. The SLA-breach predictor, looking at DPWT's current backlog and crew schedule, flags Maria's request as likely to breach. It appears on the supervisor's Escalations screen before the deadline. The supervisor reassigns it to a crew with capacity.
The crew fills the pothole. The agent, on their phone at the site, opens the Request workspace, moves it to RESOLVED, and - the state machine requires it - attaches a proof photo of the filled pothole. A resolution note: "Pothole filled, road surface restored."
Maria automatically gets a text in Spanish: "Your pothole report is resolved," with the before and after photos. If she thinks it is not actually fixed, she has a Reopen button for a set window.
On the Heat-map, Maria's pothole is one dot in a growing cluster on Annapolis Road. The Director filters to road hazards, last 90 days, and sees the cluster trending up. They flag the corridor for a resurfacing project - solving the next fifty potholes before they are reported.
That is the full arc: report -> route -> work -> predict -> resolve with proof -> aggregate to insight. Eight steps, three surfaces, one living record.
From Home -> Track a request -> enter request number or sign in -> Request detail with the live timeline. The point: nothing is a black hole; the resident can always see exactly where it stands.
A resident texts the County's CivicLoop number. The AI runs the same conversational intake over SMS - category, location (by address or cross-streets), description. Confirmation and every status update come back as SMS, in the resident's language. First-class path, not a fallback.
In the Request workspace, the agent disagrees with the AI's department. They tap Re-route, pick the correct department, give a reason. The AI Decision and the override are both recorded - the routing model learns, and the audit trail is clean.
Agent moves the request to NEEDS INFO with a question. The SLA clock pauses. The resident gets the question on their channel, in their language, replies, and the request returns to IN PROGRESS.
The AI flags a likely duplicate; the agent confirms. The duplicate is merged into the parent. Both residents continue to get the parent's updates - neither is dropped.
A resident's message is angry or describes a safety risk. The AI flags it; it lands on the supervisor's Escalations screen for a human before it becomes a complaint or a council call.
On the request workspace, the agent opens Schedule visit, picks
a date + time + alarm window, adds a short note. CivicLoop sends an
SMS + email to the resident immediately, with a .ics calendar
attachment so the visit drops onto the resident's phone calendar. The
crew can set a 24h alarm. A "Cancel" or "Complete" later writes a
Request Event on the timeline and updates the upcoming-visits panel
on the Director dashboard.
@loop (any staff)A DPWT supervisor opens /channels/dpwt, types @loop how are we doing on potholes today. The Loop persona (Document 07) replies in
the channel, signed "Loop AI", with a fresh county snapshot: open
count, breaches, last-24h status mix. The same channel handles
/breaches and /summary CP-2026-NNNNNN deterministically (no AI
call), and any CP-... typed in chat is auto-linked into
/console/[requestNumber].
On /admin, the County Admin slides the Autopilot dial from off
to route to full. Each flip is logged. With full, the next
inbound request routes, assigns to the lightest-loaded agent in that
department, and notifies the resident - all attributed to
actor='ai' with the AUTOPILOT: log prefix, all reversible at any
time.
On /admin, the County Admin clicks Run self-heal now. The
sweep finds open requests with breached or near-breach SLA,
reassigns to a supervisor in the same department, bumps priority,
posts a @first-name heads-up in the department channel, and
notifies the resident. Idempotent on a 6-hour cooldown per request.
The same sweep runs as a cron at /api/cron/self-heal (gated by
SELFHEAL_CRON_TOKEN).
The moment a request transitions to RESOLVED, a request_surveys
row is minted with a single-use token and the resident is texted +
emailed a one-tap 1-5 link to /[locale]/survey/[token]. Responses
roll into the NPS panel on the director dashboard.
A reporter, a council member's staffer, or a curious resident opens
/public. The page is anonymous, NOT locale-scoped, no PII. They
see last-7-day filed/resolved/open/median resolution/SLA on-time/NPS,
top categories, by-district, and an anonymized SVG scatter map. They
can print the page to PDF or download the underlying numbers as CSV
at /api/public/weekly.csv. No account, no friction, no excuses.
A council member's staffer opens /[locale]/council/3. The whole
director picture renders, scoped to District 3: totals, open,
resolved, SLA breaches, top categories, recent requests, and the
district's slice of the forecast.
On /[locale]/admin/locations, the County Admin enters an address
and lat/lng for a known problem corner. CivicLoop generates a
branded poster with a QR. The poster goes on a community-center
bulletin board; a resident scans it; the report flow opens with the
address, lat, and lng pre-filled (/report?address=&lat=&lng=).
For May 23, the hero flow (Section 2) is built to full presentation polish - every one of those eight steps works live, on real demo data, in English and Spanish. The secondary flows (Section 3) are built and working but shown briefly. The Admin screens (Section 1) are functional but not the focus of the pitch - they prove the system is real and configurable, they are not the wow.
Depth on the hero flow beats breadth across half-built screens. That is the scope discipline (Document 10).
Next: 07 - AI Components.