08 - Integrations & Data

CivicLoop by Ta-Tech Solutions Purpose: Every external system CivicLoop connects to, the open standard it commits to, how data flows in and out, and the integration roadmap. This is the document a County technical reviewer reads to answer "will this work with what we already have, and are we locked in."

1. The posture: open in, intelligent on top, never locked in

CivicLoop's integration philosophy is one sentence: open standard in, CivicLoop intelligence and closed-loop status on top, the County's data exportable at all times. Every integration decision below serves that posture. It is the deliberate opposite of the incumbents - whose deployments cost millions, take years, and hold the County's data hostage.

2. Open311 / GeoReport v2 - the interoperability commitment

What it is. Open311 / GeoReport v2 is an open, collaborative REST API standard for civic issue reporting. It defines a common interface for two things: viewing a jurisdiction's service definitions (categories), and submitting and tracking service requests. It has been supported since around 2010 by San Francisco, Washington DC, Boston, and dozens of other cities, and by vendors including SeeClickFix and Connected Bits.

What CivicLoop does with it. CivicLoop implements Open311 GeoReport v2 both ways:

• Inbound (CivicLoop as an Open311 endpoint). CivicLoop exposes a standards-compliant Open311 API. Third-party civic apps, regional dashboards, and the County's own future tools can submit and query requests through the open standard - not a proprietary CivicLoop API they have to learn and depend on.
• Outbound (CivicLoop as an Open311 client). CivicLoop can read from and write to other jurisdictions' Open311 endpoints - useful for regional coordination and for migration.

Why it matters to the County.

1. It answers interoperability clauses in the RFP directly and concretely - not "we have an API," but "we implement the recognized open standard."
2. It is the anti-lock-in proof. The County's request data is reachable through a public standard. If the County ever leaves CivicLoop, the data goes with them through the same standard it came in by. Contrast: an incumbent whose app residents literally cannot submit through, with no clean way out.
3. It future-proofs the platform path - when CivicLoop expands to more agencies or the County adds tools, the standard is the connective tissue.

The positioning line for the pitch: open standard in, our intelligence on top, your data always yours.

3. MyPGC / govDelivery - coexist, do not fight

The County runs MyPGC - its outbound "emails, alerts, notifications" subscription system, almost certainly Granicus govDelivery (Document 02).

CivicLoop does not propose ripping MyPGC out. It integrates:

• CivicLoop feeds MyPGC. Request-status updates generated by CivicLoop's notification engine can be pushed into the County's existing govDelivery channel, so residents who live in MyPGC still get their CivicLoop updates there.
• CivicLoop closes the gap MyPGC cannot. MyPGC is broadcast and subscription - it does not know about your specific pothole. CivicLoop's living record does. The integration gives the County both: broadcast comms through MyPGC, request-specific closed-loop comms through CivicLoop.

This is the anti-lock-in posture made concrete on the County's own turf: we make what they already paid for smarter; we do not demand they tear it out.

4. Communication channels

CivicLoop reaches residents on the channel they prefer (Document 03 - every Resident has a preferred_channel). The channel layer is pluggable; providers are configuration, not code.

Each channel is bidirectional where the medium allows: a resident can reply to an SMS or WhatsApp notification and the reply lands on the request as a comment.

5. Maps & geocoding

The geographic layer is core, not decoration - it powers the map pin, the service-area routing, the public map, and the Director's heat-map.

• Geocoding - turning a spoken or typed address, or "cross-streets near the school," into a coordinate; and reverse-geocoding a GPS point into a readable address. Pluggable provider.
• Map tiles - for the resident's pin-drop, the agent's map view, the heat-map. Cached for offline use on the resident PWA (Document 05).
• Service-area polygons - the County's council districts / planning areas / custom boundaries, stored as geographic polygons (PostGIS), so every request's location resolves to a service area for routing and analytics.
• Geospatial queries - "open requests within 500m" (duplicate detection), "requests in this council district" (analytics), "cluster detection" (trend detection) - all run in the database's geographic layer.

6. County back-end systems - the integration roadmap

The documented #1 city-side failure mode is a 311 system not connected to departmental work-order and legacy systems (Document 02). CivicLoop addresses this in stages, honestly scoped:

• v1 / pilot: The CivicLoop agent console is the work surface for the pilot department(s). For a department with no modern work-order system, CivicLoop fills the gap directly. For a department that has one, v1 uses the Open311 API and simple webhook exports so the request is visible in both places - no deep custom integration in the 9-day build, but the seam is there and standards- based.
• Phase 2: Deeper, bidirectional integration with the County's major work-order / asset-management systems (the Cityworks / Salesforce-class systems referenced in the research), so status flows both ways automatically.
• Always: Open311 in/out (Section 2) and the open-data export (Section 7) mean the County is never waiting on a custom integration to get its own data.

CivicLoop does not pretend to integrate with everything on day one. It is honest about the staging - and the open standard means the County is never stuck while a deeper integration is built.

7. Open data & public records

311 service-request data is generally public record, subject to Maryland Public Information Act requests. CivicLoop treats this as a feature, not a compliance cost:

• Open-data export. A standing, standards-aligned export of service-request data (with resident personal details removed - Document 09), suitable for the County's open-data portal. An agent fires it; the export agent (Document 07, Section 7b) can run it on a schedule.
• Public dashboard. The public map (Document 06) is itself a form of open data - residents and press can see what is being reported and resolved, addresses generalized for privacy.
• The public transparency portal at /public. A separate, anonymous, no-account, NOT-locale-scoped page that shows the County's last-7-day filed/resolved/open/median resolution/SLA on-time/NPS, top categories, by-district, and an anonymized SVG scatter map. Strict no-PII guarantee (Document 09). Designed as a governance and public-trust artifact, not a marketing surface.
• Public CSV download. /api/public/weekly.csv returns the same weekly aggregates as a machine-readable CSV. A reporter or a data-curious resident does not have to scrape the page or file an MPIA request to get the numbers - they download a file.
• FOIA / MPIA readiness. Because every request is a complete, immutable, timestamped record with a full event history, responding to a public-records request is a query, not an archaeology project.

Transparency is a selling point to a County panel, and CivicLoop ships it by default.

7a. Calendar (.ics) for scheduled visits

When an agent schedules a visit on a request (Document 06), the resident gets SMS + email with a .ics calendar attachment. The attachment is generated server-side by /api/visits/[id]/ics/route.ts and embeds:

• the request number,
• the scheduled time and duration,
• the resident-facing address (the snapshot stored on the scheduled_visits row),
• a VALARM for the configured alarm window (so the resident's calendar app pings them 24h before),
• a description that links back to /track?number=&phone=.

Calendar integration is one of the smallest, highest-trust integrations a 311 system can ship - it puts a County commitment on a resident's own calendar. No surveyed rival does it.

7b. QR codes and deep links

CivicLoop generates SVG QR codes server-side via /api/qr?data=...&size=.... Two places consume them:

• The report success page renders a tracking QR that points to /track?number=&phone= so a resident's friend or co-worker can scan the resident's phone screen and pull up the same lookup.
• The /[locale]/admin/locations poster builder lets the County Admin print a branded poster with a QR for any council district, kiosk, or known problem area. The QR encodes /report?address=&lat=&lng=&source= so a scan opens the report flow with the location pre-filled.

The report flow accepts ?address=&lat=&lng= from any QR or SMS deep-link, so a scan from a poster lands the resident directly on a pre-filled intake. The source parameter (e.g. source=poster-d3) flows into the audit log so the County can see which physical posters are driving reports.

7c. The self-heal cron endpoint

/api/cron/self-heal is a server-only POST endpoint that runs the self-heal sweep (Document 07, Component L). It is callable two ways:

• Manually from /admin via the "Run now" button (admin-gated, staff session required).
• On a schedule via any cron runner (Netlify scheduled functions, a Cloudflare Worker, or the County's own cron), gated by the optional SELFHEAL_CRON_TOKEN env. The token-gated path needs no staff session, which is what makes it cron-callable without a logged-in user. The token is configured in /admin -> Integrations.

The endpoint is idempotent on a 6-hour per-request cooldown so a runaway cron cannot spam residents or re-escalate the same request.

8. Identity & SSO

• Residents - no County identity needed; passwordless one-time codes (Document 04).
• Staff - County email + password + two-factor by default. Single sign-on against the County's identity provider (SAML / OpenID Connect) is a supported configuration, so County IT can manage CivicLoop staff access the same way they manage everything else. This is configuration on the Ta-Tech engine's existing auth layer, not new work.

9. Data ownership, portability & exit

Stated plainly because a County panel will ask:

• The County owns its data. Every request, resident record, attachment, and audit entry belongs to the County.
• It is portable at any time. Through the Open311 standard and a full structured export - not just a PDF dump, the actual data.
• Exit is clean. If the County leaves CivicLoop, it leaves with everything, in open formats. There is no hostage-taking. We intend to earn the renewal on results; the architecture guarantees the County is never trapped if we do not.

10. What is built and live (as of 2026-05-18)

• Open311 endpoint - LIVE both ways. Try it now: https://civicloop-pgc.netlify.app/api/open311/v2/services.json (read), POST to https://civicloop-pgc.netlify.app/api/open311/v2/requests.json with an api_key (write). The CivicLoop request number is the service_request_id so a third-party client and the resident see the same identifier.
• SMS + email notifications - wired into status transitions and agent replies (Twilio + Resend). Each attempt records a notifications row whether or not delivery succeeds, so the dashboard always has the audit trail.
• Maps, geocoding, browser geolocation - the resident report flow accepts an address or a one-tap GPS pin, with translated error messaging if the browser blocks location.
• MyPGC feed, deep work-order integration, SSO - specified and designed (this document), demonstrated as the roadmap, not built in the pilot window. Honestly scoped.

Next: 09 - Security, Privacy & Accessibility.